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NOTICE 


The  Department  of  Defense  Kerneiized  Secure  Operating  System  (KSOS)  is  being  pro¬ 
duced  under  contract  for  the  U.S.  Government.  KSOS  is  intended  to  be  compatible  with  the 
Western  Electric  Company's  UNIX™ Operating  System  (a  proprietary  product)  KSOS  is 
not  part  of  the  UNIX  license  software  and  use  of  KSOS  is  independent  of  any  UNIX  license 
agreement.  Use  of  KSOS  does  not  authorize  use  of  UNIX  in  the  absence  of  an  appropriate 
licensing  ageement. 

This  document,  furnished  in  accordance  with  Contract  MDA  903-77-C-0333,  shall  not  be 
disclosed  outside  the  Government  and  shall  not  be  duplicated,  used,  or  disclosed  in  whole  or 
in  part  for  any  purpose  other  than  to  evaluate  the  contractor’s  performance  of  Phase  I  of  the 
contract:  upon  completion  of  Phase  I  of  the  contract,  the  Government  shall  have  the  right  to 
duplicate,  use,  or  disclose  the  data  to  the  extent  provided  in  the  contract. 

The  contents  of  this  document  shall  be  handled  as  proprietary  information  until  5  April 
1978.  After  that  time,  the  Government  may  distribute  the  document  as  it  sees  fit. 


UNIX  and  PWB/'UNIX  are  trade/service  marlcs  of  the  Bell  System. 

DEC  and  PDP  are  registered  trademarks  of  the  Digital  Equipment  Corporation.  Maynard, 
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\  ABSTRACT  — 1 - - 

''“This  report  presents  a  discussion  of  the  implementation  plan 
for  the  KSOS  project*  Programming  techniques,  implementation 
tools,  implementation  activity  Integrity,  Impact  of  techniques  on 
verification  and  performance,  testing,  and  external  configuration 
management  are  discussed* 


The  Implementation  plan  developed  in  the  sections  that  follow  is  Intended 
to  provide  the  reader  with  an  understanding  of  the  implementation  methodology 
that  Ford  Aerospace  &  Communications  Corporation  (FACC)  will  use  during  the 
detailed  design  and  coding  of  KSOS.  This  report  is  divided  into  major  sec¬ 
tions  chat  discuss  programming  techniques,  FACC  programming  support  tools, 
verification  and  performance  implications  of  FACC  implementation  methodology, 
implementation  security,  testing  plans,  and  configuration  management.  ^ — - _ 


I .  Programming  Techniques 


1.1.  Programming  Protocol 

This  section  discusses  the  programming  protocol  to  be  used  during  the 
development  of  KSOS.  A  programming  protocol  is  the  creative  use  of  standard 
language  constructs  within  a  management  defined  and  enforced  structure.  This 
structure  will  provide  style  standards  for  all  code  produced  by  the  FACC 
implementation  team.  Engineering  models  will  be  developed  in  selected  high- 
risk  areas  of  the  project  in  order  to  provide  quantitative  performance  infor¬ 
mation  for  use  in  detail  design  decisions.  FACC  plans  to  specify  program 
design  in  a  hierarchical  design  language  (HDL)  in  lieu  of  flowcharts.  HDL  is 
an  FACC  product  that  runs  under  UNIX*tm.  Documentation  is  provided  in  Appen¬ 
dix  A.  Formal  code  inspection  [Fagan,  1976]  will  be  used  as  the  vehicle  for 
quality  assurance,  style  enforcement  and  programmer  education. 
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1.1.1.  Language  Usage  Standards 

The  subject  of  standards  is  generally  unpopular  with  programmers  because 
of  the  notion  that  standards  stifle  creativity.  Well-selected  standards  do 
just  the  opposite,  since  the  programmer's  creativity  need  not  be  spent  making 
mundane  stylistic  decisions.  Standards  also  have  a  positive  effect  on  relia¬ 
bility  because  they  encourage  uniform  programming  style.  An  Illustration  of 
the  type  of  programming  standards  to  be  applied  In  the  KSOS  project  Is  given 
in  Appendix  B,  which  discusses  standards  for  writing  C  programs.  The  neces¬ 
sary  changes  to  embrace  the  KSOS  programming  language  (KPL)  will  be  made  to 
the  programming  standards  document  when  the  KPL  is  decided.  Drastic  altera¬ 
tion  of  the  standards  Is  not  expected.  With  the  formal  inspection  procedure 
chat  FACC  will  use,  adherence  to  programming  standards  will  be  ensured.  A 
discussion  of  this  Inspection  process  Is  presented  In  Section  1.5. 

Programming  standards  are  not  viewed  as  absolute  rules.  Any  proposed 
deviation  from  these  guidelines  can  be  publicly  scrutinized  and  approved,  if 
justified.  A  sec  of  standards  will  be  drawn  up  once  the  programming  language 
for  kernel  implementation  is  determined.  These  standards  and  ocher,  slmiliar 
materials  will  be  collected  together  into  a  KSOS  Programmer's  Notebook.  These 
notebooks  will  be  distributed  to  all  project  members,  and  will  be  periodically 
updated.  Wherever  practical,  automated  tools  for  formatting,  editing,  archiv¬ 
ing,  and  auditing  will  be  used.  (See  Section  1.5  of  this  document  for  addi¬ 
tional  Information  on  implementation  tools.) 

1.1.2.  Structure 

Each  procedure  will  contain  a  standard  header  block  that  specifies  the 
information  shown  in  Figure  1-1. 

MODULE  NAME:  name.c 

FUNCTION:  Synopsis  of  operation. 

ASSUMPTIONS:  Limits,  etc. 

ALGORITHM:  References  &  explanation. 

PARAMETERS:  Input  &  output. 

RETURNS:  Output  value. 

GLOBALS:  Variables  &  their  meaning. 

MODULES  CALLED:  Library  &  programs. 

CALLED  BY:  What  programs  use  this  one. 

HISTORY:  Who,  when,  what,  why. 

AUTHOR: 

DATE:  Jan  28  1978 

VERSION: 


Figure  1-1.  Standard  Module  Header  Concents 


This  header  block  forms  the  basic  entry  in  a  Module  Development  Folder  chat  is 
maintained  for  each  module  throughout  the  development  and  testing  cycle.  FACC 
plans  to  maintain  online  versions  of  the  Module  Development  Folder  as  a  part 
of  the  program  source. 
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The  procedure  format  will  be  maintained  with  a  standardized  lexical 
reformatter/indenter.  All  data  declarations  will  be  commented  in  the  source 
code,  since  understanding  of  the  data  abstraction  is  central  to  understanding 
the  program*  The  executable  statements  of  each  module  should  not  be  exces¬ 
sively  commented.  A  reasonable  guideline  is  to  read  the  code  (at  formal 
inspections)  and  insert  comments  at  points  where  questions  arise.  Commentary 
should  be  notes  to  the  reader,  not  a  description  of  logic  that  is  fully 
described  by  the  code  itself.  Accuracy  of  the  logic  description  in  the  stan¬ 
dard  module  header  will  be  ensured  by  the  formal  inspection  process. 

1.1.3.  Information  Hiding 

One  of  the  key  style  principles  will  be  to  delay  program  binding  as  long 
as  possible,  consistent  with  efficiency  considerations.  SRI  International's 
Hierarchical  Design  Methodology  (HDM)  [Neumann,  1976]  being  used  for  KSOS  is 
based  on  the  notion  of  successive  levels  of  information  hiding  and  delayed 
binding.  In  particular,  access  functions  will  be  used  to  manipulate  global 
status  information  rather  than  providing  direct  access  to  global  data  struc¬ 
tures.  The  principle  of  decision,  or  information  hiding  [Parnas  72],  is  cen¬ 
tral  to  the  design  of  a  provably  secure  system.  This  principle  also  serves 
to  improve  reliability  and  reduce  the  system's  sensitivity  to  change.  A 
structure  designed  according  to  information-hiding  principles  can  often  result 
in  a  module  division  that  is  quite  different  from  conventional  decompositions 
[Parnas  77]. 

Each  design  decision  about  data  representation  or  event  sequencing  is 
"hidden"  within  a  module.  As  a  result,  assumptions  about  data  structures  are 
confined  to  a  single  module  and  a  change  in  these  assumptions  affects  only  one 
module.  Such  a  change  is  said  to  be  transparent.  As  a  result  of  Information 
hiding,  system  maintainability  is  expected  to  be  significantly  better  than 
that  normally  available  with  globally-known  system  tables. 

The  cost  of  rigorous  information-hiding  may  be  paid  in  reduced  perfor¬ 
mance,  since  information  accesses  may  be  converted  into  procedure  invocations 
rather  than  direct  structure  references.  This  problem  may  be  avoided  if  the 
programming  language  provides  inline  code-generation  facilities;  invocation  of 
an  Inline-procedure  must  be  indistinguishable  syntactically  from  actual  pro¬ 
cedure  calls.  FACC  accepts  the  potential  reduction  in  "absolute  efficiency" 
that  results  from  decision-hiding  as  a  necessary  price  to  pay  for  resilient 
software  that  has  low  sensitivity  to  structural  modification.  Violations  of 
the  "information-hiding"  principle  will  be  explicitly  noted  in  design  and  code 
inspections.  It  is  anticipated  that  the  only  exceptions  to  "information- 
hiding"  will  be  made  in  program  areas  found  to  be  on  critical  timing  paths. 

Quantative  assessment  of  the  performance  cost  of  information  hiding  is 
not  possible  at  the  present  time.  When  overly  expensive  hiding  is  discovered, 
redesign  of  data  access  mechanisms  to  distribute  information  structure 
knowledge  to  time-critical  users  will  be  undertaken  when  necessary.  However, 
conventional  wisdom  about  program  behavior  Indicated  that  execution  ineffi¬ 
ciencies  tend  to  be  clustered  (10X  code  ->  90Z  time)  and  that  significant 
inefficiencies  can  be  isolated  at  relatively  low  expense  with  proper  instru¬ 
mentation  of  the  program. 
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1. 1.4.  Readability 

Programming  style  that  emphasizes  readabilcy  and  simplicity  will  be 
required  throughout  the  KSOS  project.  A  sample  of  these  standards  for  C  pro¬ 
grams  is  presented  in  Appendix  3.  Formatting  standards  will  be  enforced  by 
means  of  indancers  such  as  that  described  in  Appendix  C. 

1.1.5.  Maintenance 

Life-cycle  cost  studies  indicate  that  average  computer  programs  have  a 
maintenance  cost  that  is  far  greater  than  the  development  cost.  FACC  will 
emphasize  maintainability  during  the  code  development  process  in  order  to 
minimize  the  long-term  costs  associated  with  KSOS  support*  Transparency 
assists  maintenance  because  changes  are  localized  to  a  single  module.  Since 
Che  kernel  must  be  reverlfied  after  any  modification,  localization  is  impor¬ 
tant  to  change-containment  and  reduction  of  reverif ication  costs.  Details  of 
FACC's  maintenance  procedures  are  discussed  in  a  separate  document,  the  Sup¬ 
port  and  Maintenance  Plan. 

1.2.  Engineering  Models 

The  KSOS  project  presents  significant  development  challenges  on  several 
fronts.  Since  the  implementation  effort  must  address  the  possibly  conflicting 
objectives  of  secure  operation  and  high  performance,  FACC  believes  that 
engineering  models  of  significant  portions  of  the  security  kernel  and  the 
UNIX*tm  emulator  will  need  to  be  built  before  detailed  design  specifications 
can  be  drawn  up.  FACC  intends  to  build  enough  of  the  kernel  to  evaluate  tim¬ 
ing  limitations  of  processes  and  file  mechanisms  proposed  in  the  kernel 
design.  Instrumentation  of  the  engineering  models  will  allow  quantitative 
performance  measurement  and  an  early  basis  for  performance  estimation  of  the 
production  system. 

In  his  book  of  essays  on  software  engineering,  [Brooks  75]  argues  that 
che  initial  system  developed  in  a  project  should  not  be  delivered,  but  used  as 
a  test-bed  for  che  system  to  be  delivered.  In  a  similar  vein,  [Royce  70] 
advises  commitment  of  about  one  third  of  che  project's  time  budget  to  "doing 
ic  twice",  with  che  first  implementation  serving  as  a  simulation  of  the 
deliverable  (second)  version.  Although  FACC  plans  to  devote  far  less  resources 
than  Royce  suggests,  Che  basic  principal  will  be  followed  in  KSOS.  FACC  feels 
chat  such  a  strategy  offers  che  Government  far  lass  risk  Chan  proceeding  ahead 
with  no  internal  engineering  model  efforts. 

The  two  KSOS  prototypes  have  been  studied  (and  will  be  the  object  of  much 
fucure  study)  co  provide  guidance  in  the  FACC  design  effort.  FACC  believes 
Chat  both  prototypes  fall  short  of  the  requirements  for  a  production  version 
of  KSOS.  Ic  is  clear  chat  simple  extensions  to  either  kernel  will  not  satisfy 
all  requirements  for  a  production  system  (including  performance).  Thus, 
FACC/SRI  have  embarked  on  a  course  that  seeks  to  preserve  che  best  features  of 
each  system  in  a  unified  design. 
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1.2.1.  Evaluation  Models  for  High-Risk  Components 

An  engineering  model  is  a  skeletal  program  that  implements  crucial  algo¬ 
rithms  for  the  purpose  of  timing,  storage,  and  logic  validation.  Before 
embarking  on  a  detailed  design  effort,  engineering  models  of  the  most  critical 
components  of  the  kernel  and  the  UNIX*tm  emulator  will  be  developed.  The 
resulcs  of  these  modelling  efforts  will  be  used  to  guide  the  generation  of 
detailed  design  specifications.  Engineering  models,  while  developed  as 
disposable  software,  will  affect  the  structure  of  the  detailed  design  and  the 
the  scyle  for  the  full-scale  implementation  that  follows.  The  resulting  pro¬ 
grams  will  serve  as  models  for  subsequent  full-scale  implementation  efforts. 

Because  of  the  importance  of  feedback  to  the  design  process,  the 
engineering  model  development  will  be  undertaken  very  early  in  Phase  II  of  the 
KSOS  project.  The  model  development  team  will  proceed  with  a  top-down  design 
and  development  effort  based  on  the  formal  specifications  chat  result  from 
Phase  I.  These  engineering  models  will  provide  the  quantative  performance 
basis  for  a  final  design  that  assures  adequate  speed  of  operation  of  the  pro¬ 
duction  version  of  KSOS.  This  throw-away  code  is  expected  to  provide  quanta- 
dve  data  on  algorithm  performance.  In  particular,  FACC  expects  to  implement 
engineering  models  of  the  Security  Kernel  and  performance-sensitive  portions 
of  the  UNIX*tm  emulator.  Although  a  great  deal  about  design  approaches  has 
been  learned  from  the  MITRE  and  UCLA  security  projects,  FACC  does  not  believe 
that  detailed  design  of  an  assured-performance  system  based  on  an  extended 
MITRE/UCLA  design  can  be  undertaken  honestly  without  direct  modelling  efforts. 

The  throw-away  code  produced  in  the  engineering  models  is  expected  to 
reduce  the  cost  of  the  project  by  exposing  infeasible  implementation  stra¬ 
tegies  early  in  the  detailed  design  phase.  Feedback  to  the  designer  of  data 
from  a  "live"  system  can  be  extremely  valuable  In  disspelling  "folklore." 

1.2.2.  Programming  S  tanda  rds 

The  engineering  models  are  also  expected  to  serve  as  a  test  for  the 
administrative  aspects  of  the  KSOS  effort:  configuration  control,  design  and 
code  inspections,  and  documentation  methods  chat  FACC  will  use  during  detailed 
design  and  subsequent  coding.  FACC  believes  chat  we  can  make  better  use  of 
our  resources  if  we  track  them  carefully.  Furthermore,  the  use  of  inspections 
at  the  engineering  model  stage  allows  us  to  get  feedback  on  the  inspection 
process  itself,  as  well  as  train  project  personnel  in  its  use.  The  engineer¬ 
ing  models  are  expected  to  provide  educational  benefits  to  the  whole  develop¬ 
ment  team.  Overview  documents  that  are  understandable,  informative  and  current 
will  be  used  to  document  each  model.  These  overview  documents  will  be  distri¬ 
buted  as  updates  to  the  Programmer's  Notebook.  Every  detailed  designer  must 
have  an  understanding  of  the  design  based  on  a  world-view  of  project  objec¬ 
tives  and  design  trade-offs.  Without  such  a  consistent  frame  of  reference, 
detailed  design  can  easily  compromise  performance,  security,  or  maintainabil¬ 
ity  . 
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1.3.  Product  Level  Specifications 


1.3.1*  High-Level  System  Documentation 

Subject  to  Government  approval,  FACC  plans  to  use  a  hierarchical  design 
language  (HCL)  in  lieu  of  flowcharts.  System  documentation  requirements  vary 
with  che  level  of  detail.  While  graphical  representations  of  program  struc¬ 
ture  have  been  required  by  tradition,  there  has  been  considerable  discussion 
of  che  utility  of  flowcharts  in  recent  years. 

Flowcharts  show  che  decision  structure  of  a  program,  which  is  only  one 
aspect  of  its  structure.  They  show  decision  structure  rather  elegantly 
when  che  flowchart  is  one  page,  but  che  overview  breaks  down  badly  when 
one  has  multiple  pages,  sewed  together  with  numbered  exits  and  connectors. 
The  one-page  flowchart  becomes  essentially  a  diagram  of  program  structure 
and  of  phases  or  steps.  [1] 

Shneiderman's  recent  studies  conclude  that 

Our  experiments  have  noc  demonstrated  the  utility  of  detailed  flowcharts 
in  program  composition,  comprehension,  debugging,  or  modification.  [2] 

FACC  plans  to  use  a  hierarcnical  design  language  (HDL)  to  represent  all 
levels  of  program  design.  Where  a  very  high  level  structure  overview  appears 
useful,  structure  charts  may  be  produced* 

1.3.2.  Hierarchical  Design  Language  (HDL) 

The  Hierarchical  Design  Language  (HDL)  is  a  tool  that  aids  design  and 
documentation  of  systems  of  programs.  HDL  is  modelled  after  the  Caine,  Farber 
and  Gordon,  Inc.  (CFG)  Program  Design  Language  system.  An  HDL  design  Is 
written  in  "structured  English",  with  control  represented  in  terms  of  C- 
language  control  constructs.  HDL  is  a  program  developed  by  FACC  for  use  on 
the  UNIX*tm  system.  Appendix  A  contains  documentation  for  HDL. 

Input  to  the  HDL  processor  consists  of  files  that  are  created  and  main¬ 
tained  with  the  program  creation  editor  (discussed  below)  that  runs  under 
UNIX*tm.  Output  of  HDL  is  a  working  design  document  consisting  of  a  table  or 
contents,  a  lexically  indented  listing  of  the  procedure  designs,  and  a  cross- 
reference  of  procedure  calls  and  global  variable  usage.  Procedure  calling 
trees  can  be  produced  from  HDL  source  through  use  of  "nn",  another  FACC 
developed  tool.  Appendix  C  documents  a  set  of  representative  program  develop¬ 
ment  tools. 

HDL  output  is  a  replacement  for  flowcharts.  It  is  machine  readable, 
easier  to  process,  easier  to  maintain,  and  easier  to  read.  Because  HDL  Is 
textual.  It  channels  programmer  energies  away  from  mechanical  drawing  and  into 
productive,  technical  design.  Like  a  flowchart,  HDL  can  be  written  at  che 
level  of  detail  appropriate  to  che  current  design  level.  A  designer  can  start 
with  a  few  pages  of  HDL  chat  give  general  system  structure.  As  the  hierarchi¬ 
cal  design  expands,  che  design  specification  can  be  expanded  precisely  and 
consistently. 

1.  Brooks,  1975,  p  168 
2*  Shneiderman,  1977,  p  381 
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The  development  of  KDL  is  part  of  FACC'a  continuing  IR&D  in  software 
technology  development.  FACC  has  chosen  to  use  KDL  rather  chan  PDL  because 
HDL  provides: 

*  Enhanced  control  structure  notation. 

*  Efficient  operation  under  UNIX*tm. 

HDL  or  associated  design-aid  tools  will  provide  greater  utility  and  flexibil¬ 
ity  than  CFG's  PDL  processor. 

1.4.  Specification-Design-Implementation  Correspondence 


Synchronization  of  the  formal  specification,  the  HDL  design,  and  the  KSOS 
programming  language  (KPL)  implementation  are  of  significant  concern  to  FACC. 
The  classical  specification  to  design  to  Implementation  (l.e.,  SPECIAL  ->  HDL 
->  KPL)  evolution  requires  two  levels  of  Interface  and  translation.  FACC 
plans  Co  derive  HDL  specifications  from  the  SPECIAL  representation  of  the  for¬ 
mal  specification  for  the  component.  Realization  of  the  KPL  implementation 
will  also  be  made  from  the  formal  specification,  using  the  HDL  representation 
as  commentary  and  guidance.  The  SPECIAL  representation  will  be  used  as  the 
controlling  element  at  all  times. 


1.5.  Formal  Code  Inspection 

Successful  management  requires  planning,  measurement  and  control.  All 
these  elements  are  especially  significant  in  the  software  development  process, 
where  there  is  a  tradition  of  highly  individualized  program  development  proto¬ 
cols.  Under  the  traditional  regimen,  the  manager  is  usually  limite 

d  to  plan¬ 
ning,  with  control  of  the  project  an  elluslve,  unrealizable  goal  because 
effective  measurement  is  unattainable.  Measurement  implies  Known  standards 
coupled  with  careful  inspection.  In  short,  consistent  and  vigorous  discipline 
is  required  in  setting  and  enforcing  standards.  Since  establishment  of 
blindly-enforced  rules  can  stifle  programming  work,  a  clearly  understood 
mechanism  for  justifying  "rule-breaking"  should  be  specified. 

Numerous  organizational  techniques  have  been  applied  to  the  program 
development  process  in  order  to  improve  software  quality.  Among  these  tech¬ 
niques,  variants  of  the  Chief  Programmer  Team  [Brooks  75,  Baker  71]  have  been 
widely  discussed  and  utilized.  Major  elements  of  each  of  these  efforts  have 
been  limitation  of  team  size  and  deep  involvement  of  the  team  leader  In  criti¬ 
cal  details  of  system  design  and  implementation.  Programmer  attitude  towards 
their  products  have  also  been  discussed  extensively  [Weinberg  71,  Aron  75,  Yeh 
77].  Use  of  structured  walk-throughs  and  teams  that  naturally  practice  "ego¬ 
less"  programming  has  yielded  good  results  in  some  development  efforts.  FACC 
proposes  to  take  the  effort  a  step  further,  applying  techniques  of  formal  code 
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inspection  (Fagan  76]  to  Improve  the  quality  control  In  Che  code  development 
process* 

The  inspection  process  is  divided  into  the  five  general  types  of  activi¬ 
ties  shown  in  Figure  1-3.  The  functions  of  each  activity  will  be  explained  in 
detail  in  the  Programming  and  Specification  Standards  that  will  be  prepared  as 
a  part  of  Phase  II  of  the  KSOS  project. 


OPERATION 

DESCRIPTION 

PLANNING 

Establishing  the 
schedules,  desig¬ 
nating  the  parti¬ 
cipants,  and 
requesting  the 
inspection 
material 

PREPARATION 

Participants  use 
the  distributed 
material  to 
prepare  for  the 
inspection 

INSPECTION 

Formal  process  of 
inspecting  the 
distributed 
material 

REWORK 

The  process  of 
fixing  chose  prob¬ 
lems  identified  at 
che  inspection 

FOLLOW-UP 

Maintain  accounta¬ 
bility  for  problem 
resolution 

OBJECTIVES 

COMMENTS 

To  assure  that 
schedules  and  par¬ 
ticipants  are 
established  and 
materials  avail¬ 
able 

Occurs  before 
inspection 
macerial  is  avail- 
ab  le 

Allows  partici¬ 
pants  to  come  to 

Che  Inspection 
ready  to  find 
errors 

Occurs  after  che 
material  is  dis¬ 
tributed  and 
before  the  inspec¬ 
tion 

To  find  errors  and 
otamlsslons 

A  meeting  led  by 
the  Moderator; 
held  after  ail 
preparation  is 
complete 

Provide  time  for 
identified  prob¬ 
lems  to  be 
corrected 

Moderator  deter¬ 
mined  necessity  of 
reinspeccion  based 
on  number  and  mag¬ 
nitude  of  problems 

To  insure  that  all 
problems  are 
satisfactorily 
resolved 

Inspection  exit 
criteria  require 
resolution  of  all 
problems;  on  exit, 
update  inspection 
Data  Base 

Figure  1-3.  Inspection  Activities  and  Objectives 
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1.5.1.  Quality  Assurance  and  Education 

KSOS  stands  or  falls  on  the  accuracy  of  the  translation  of  verified 
specifications  into  code.  FACC  proposes  to  use  an  implementation  language 
that  provides  a  basis  for  subsequent  automated  verification  of  the  code-to- 
specif ication  correspondence.  Code  inspection  provides  tangible  mechanisms 
for  programmer  education  in  matters  of  style  and  language  usage,  as  well  as  a 
management  tool  for  identification  of  problem  areas  and  enforcement  of  pro¬ 
gramming  standards. 

Review  (Inspection)  takes  place  in  a  formal  atmosphere,  with  a  specific 
review  objective  of  finding  errors.  Note  that  redesign  is  not  carried  out  at 
review  meetings.  The  review  process  should  include  people  in  the  following 
roles : 

a.  Moderator:  A  competent  programmer  who  need  not  be  an  expert  in  the  pro¬ 
gram  being  inspected.  The  moderator  manages  the  inspection  team  and 
offers  leadership.  He  is  the  inspection  coach  and  resource  manager. 

b.  Designer:  The  programmer  responsible  for  the  design. 

c.  Implementor:  The  programmer  responsible  for  translating  the  design  to 
code . 

d.  Tester:  The  programmer  responsible  for  writing  and  executing  test  cases 
for  the  design  and  implementation. 

When  the  roles  are  not  clear-cut,  it  is  often  advantagous  to  bring  in  others 
to  fill  each  role.  It  has  been  found  that  four  people  constitute  a  good  sized 
inspection  team.  However,  if  the  code  involves  a  large  number  of  interfaces, 
programmers  of  code  related  to  these  interfaces  may  profitably  be  involved  in 
the  inspection  process.  The  inspection  process  will  not  be  used  for  program¬ 
mer  evaluation  (no  matter  how  tempting  it  may  be  to  management)  since  the  pro¬ 
grammer  evaluation  mode  destroys  the  candor  of  an  Inspection  and  turns  it  into 
an  inquisition  or  a  bland  rubber-stamp  peer  approval  exercise. 

Time  for  inspections  and  resulting  rework  of  code  will  be  scheduled  and 
managed  with  the  same  attention  given  to  all  other  project  activities.  Two 
inspections  are  scheduled  for  each  module.  The  first,  a  Design  Completion 
Review,  is  scheduled  when  detail  design  has  reached  a  level  where  each  design 
statement  is  estimated  to  correspond  to  three  to  ten  implementation  state¬ 
ments.  The  second  inspection,  the  Code  Completion  Review,  takes  place  after 
the  first  diagnostic-free  compilation  of  the  module  is  obtained.  These  are 
checkpoints  in  the  development  process  through  which  every  module  must  pass. 

FACC  cannot  over-emphasize  the  importance  of  programmer  education.  Since 
KSOS  is  an  advanced  development  project,  with  code  to  be  written  for  a  yet- 
to-be-implemented  compiler,  FACC/SRI  must  provide  an  effective  mechanism  for 
programmer  education  and  quality  assurance.  We  believe  that  a  program  of  for¬ 
mal  design  and  code  inspection  provides  the  needed  environment. 
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1.5.2.  Security 

The  use  of  the  formal  inspection  program  will  enhance  the  security  of  the 
development  process  by  exposing  each  module  to  critical  review  by  a  team  of 
knowledgeable  Inspectors.  If  simplicity  and  visibility  of  code  Is  assumed, 
introduction  of  specious  or  subvertible  code  would  require  collusion  or  decep¬ 
tion  of  the  entire  inspection  team,  a  highly  unlikely  occurrence. 

1.5.3.  Ocher  Applications 

Documentation  and  testing  are  as  important  to  the  success  of  the  KSOS 
project  as  coding.  We  therefore  plan  to  exercise  the  same  qualicy  control  on 
all  these  activities.  Documentation  will  be  subject  to  formal  reviews  at  the 
outline  and  draft  stages;  test  planning  will  likewise  be  subject  to  design  and 
implementation  reviews. 

1.6.  Implementation  Tools 

KSOS  will  be  implemented  in  the  environment  provided  by  the  Programmer's 
Workbench  (PW3)  ilvie  77,  Doiotta  76].  This  UNIX*tm-based  program  develop¬ 
ment,  management,  maintenance,  and  testing  cool  provides  the  facilities  needed 
co  carry  out  che  complex  development  and  maintenance  activities  required  by 
the  KSOS  project.  In  addition  co  Che  facilities  available  through  PUB,  FACC 
has  implemented  a  set  of  development  tools  as  a  part  of  its  on-going  IRAD 
software  engineering  efforts.  A  discussion  of  FACC  development  tools  is  pro¬ 
vided  in  Appendix  C. 

1.6.1.  Interactive  Program  Creation  Editor 

An  editor  that  is  language-sensitive,  understanding  syntax  and  limited 
semantics,  can  enforce  programming  and  documentation  standards  as  well  as  pro¬ 
vide  language-dependent  formatting  and  text  generation  capabilities.  The  FACC 
program  creation  editor  (PCE)  checks  for  balanced  parenthesis,  generates  stan¬ 
dard  module  headers,  automatically  indents  program  text  lexicographically,  and 
contains  a  mechanism  for  rapid  language  construct  insertion.  In  addition,  the 
PCE  contains  a  number  of  editing  commands  (a  superset  of  those  provided  by  the 
UNIX*tm  editor,  "ed"). 

1.6.2.  Source  Level  Configuration  Control 

The  development  schedule  for  KSOS  requires  that  several  programming  teams 
will  be  concurrently  writing  and  testing  portions  of  the  system.  In  order  to 
provide  an  auditable  system  at  every  phase  of  Implementation,  configuration 
control  will  be  enforced  through  use  of  an  automated  library  control  and 
maintenance  system.  FACC  will  implement  source-level  configuration  control 
through  che  Source  Code  Control  System  (SCCS)  [Rochkind  75]  that  is  part  of 
the  Programmer's  Workbench  (PWB/UNIX*tm) . 

Use  of  SCCS  will  provide  a  complete  audit  trail  for  systems  development, 
repeacable  incremental  systems,  and  che  basis  for  subsequent  maintenance  of 
the  developed  system.  SCCS  will  be  used  for  the  system  integration  library  as 
well  as  individual  development  libraries.  Each  version  will  receive  a  unique 
version  number.  This  number  will  be  used  for  inspections,  modification 
requests,  and  documentation.  The  SCCS  will  be  used  co  control  all  forms  of 
macnine-readab le  text  created  or  maintained  with  source  editors. 
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1.6«3.  Documentation 

Machine  readable  document  source  will  be  generated  for  all  non-pictorial 
documents  required  by  the  KSOS  project.  All  such  prose-form  documentation 
will  be  produced  under  configuration  control.  Sample  documentation  standards 
are  discussed  in  Appendix  D.  Configuration  control  will  be  achieved  by  use  of 
project-standard  documentation  macros  for  use  with  troff/nroff  and  formal 
documentation  inspections. 

1.6.4.  Design/Impleaentatlon  Continuity 

The  FACC/SRI  design  and  specification  team  assembled  in  Phase  I  of  the 
KSOS  project  will  continue  to  exist  as  an  implementation  team  during  Phase  II, 
with  most  personnel  assuming  positions  as  detailed  designers  and  lead  program¬ 
mers  for  the  implementation  phase. 

Figure  1-4  shows  the  proposed  top-level  structure  for  the  KSOS  Phase  II 
implementation  team.  All  members  are  currently  participating  in  the  Phase  I 
design  specification  effort.  Personnel  named  in  Figure  1-4  will  have  respon¬ 
sibility  as  team  leaders  in  their  respective  functional  areas.  All  personnel 
in  che  KSOS  project  will  be  available  to  work  as  members  of  the  various  teams. 
The  Implementation  Manager  will  report  directly  to  the  KSOS  Program  Manager, 
Dr.  M.  S.  Pliner.  Dr.  E.  J.  McCauley  will  continue  to  provide  technical  sup¬ 
port  to  the  KSOS  project  throughout  Phase  II;  he  will  spend  approximately  half 
of  his  time  on  the  KSOS  project  during  Phase  II,  continuing  in  his  role  as 
principal  engineer  and  technical  adviser  to  the  project. 


1.6.5.  Source  Back-up  Plan 


All  implementation  source  and  documentation  files  will  be  maintained  in 
machine  readable  form  on  che  GFE  PDP-11/70.  In  order  to  ensure  that  data  loss 
due  to  a  hardware,  software,  or  human  error  will  not  adversely  affect  the  pro¬ 
ject,  a  back-up  archival  tape  system  will  be  maintained.  This  system  will  be 
entirely  separate  from  any  secure  copy  system.  Should  this  back-up  be  used  to 
restore  part  or  all  of  the  source  files,  a  verification  check  will  be  made  of 
the  differences  between  the  restored  version  and  the  last  secure  copy.  Backup 
copies  of  development  files  will  be  made  on  a  daily  basis  with  a  weekly  tape 
being  saved  for  one  month  and  che  last  weekly  tape  of  the  month  being  saved 
for  che  duration  of  the  project.  This  mechanism  will  provide  both  an  immediate 
back-up  and  an  archive  extending  over  the  life  of  the  project.  The  weekly  and 
monthly  save  tapes  will  be  stored  at  a  different  secure  location  to  reduce  che 
chances  of  loss  due  to  a  physical  plant  disaster.  In  addition  to  the  above 
measures,  the  PWD  SCCS  will  provide  a  running  file  of  DELTAS  for  all 
configuration-controlled  software . 

1.6.6.  Development  Support 

A  DEC  PDP-11/45  running  PWB/UNIX*tm  will  be  used  to  support  the  KSOS 
effort  at  no  cost  to  the  Government.  This  machine  will  be  equipped  with  124k 
of  memory,  a  large  disk,  tape  drive,  printer,  and  at  least  8  terminals.  It 
will  be  connected  by  a  dedicated  line  to  the  SRI  DECsysteo  20  and  will  be  able 
to  access  che  specification  and  verification  tools  available  on  the  SRI 
machine.  The  PDP-11/45  will  be  located  in  a  controlled  environment  near  the 
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GFE  PDP-11/70  and  will  be  available  as  an  alternate  development  machine  In  Che 
event  of  extended  GFE  machine  hardware  failure.  When  secure  operation  of 
either  PDP-11  Is  required,  all  communications  lines  will  be  disconnected  from 
the  computer  system. 
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2.  Implementation  Activity  Integrity 

FACC  provides  a  physical  plant  appropriate  for  protecting  and  maintaining 
the  KSOS  development  effort*  This  section  also  discussed  techniques  for 
secure  configuration  control  of  the  formal  specifications  for  KSOS  and  the 
resulting  source  code. 

2.1.  Physical  Plant 

FACC  is  located  on  a  52  acre  site  in  Palo  Alto,  California.  Floor  space 
totals  more  chan  one  million  square  feet,  of  which  more  than  85,000  square 
feet  are  vaulted  areas  suitable  for  intelligence  systems.  There  are  raised 
floor  equipment  areas  that  can  be  run  from  UNCLASSIFIED  through  TOP  SECRET. 

FACC  has  TOP  SECRET  facility  clearance.  The  cognizant  government  security 
office  is:  DCASR,  (D&FM)  San  Francisco,  866  Malcolm  Road,  Burlingame,  CA 
94010. 


FACC  has  a  proprietary  Guard  Force.  Plant  guards  and  five  video  entrance 
booths  monitor  all  entrances  to  FACC  on  a  24-hour  basis,  7  days  a  week.  The 
control  console  for  the  video  booths  is  located  in  Plant  Protection.  Identif¬ 
ication  is  made  by  photographic  identity  badges.  Preemployment,  as  well  as 
postemployment,  investigations  on  all  FACC  personnel  are  conducted  by  a  FACC 
employed  professional  investigator.  Visitor  Control  and  Master  Document  Con¬ 
trol  are  integrated  units  within  Government  Security  Operations.  Document 
Control  custodians  are  assigned  custodial  duties  for  Department  of  Defense 
classified  material  in  FACC  Master  Document  Control  and  the  FACC  Program 
Office. 

FACC  has  a  secure  communication  channel  through  an  AUTODIN  Terminal. 
When  necessary,  as  directed  by  customer  requirements,  the  Armed  Forces  Courier 
Service  is  available.  Delivery  and  pickup  are  on  Monday,  Wednesday,  and  Fri¬ 
day.  The  courier  station  is  located  in  the  Presidio  of  San  Francisco.  The 
U.S.  Postal  Service  can  also  be  utilized  for  registry  and  delivery  of  classi¬ 
fied  material.  All  such  material,  with  the  exception  of  special  intelligence 
information,  is  delivered  directly  to  Master  Document  Control.  It  is  opened 
there,  and  the  material  is  brought  into  the  accountability  system. 

2.2.  Design  Security 

FACC  will  fully  comply  with  both  the  letter  and  the  spirit  of  RFP  Para¬ 
graph  J-4  and  the  applicable  DoD  security  policies.  The  master  copy  of  the 
design  and  code  will  be  maintained  at  the  SECRET  level.  Copies  can  be  treated 
as  UNCLASSIFIED.  FACC  proposes  to  accomplish  this  in  the  following  way.  The 
master  copy  of  the  design  (i.e.,  the  formal  specifications  in  SPECIAL)  will  be 
maintained  on  a  secure  system.  Under  ARPA-TTO  sponsorship,  a  secure  TENEX  is 
available  at  Moffett-ARC,  located  approximately  three  miles  from  FACC.  This 
system  regularly  provides  a  SECRET-level  time-sharing  environment.  This  sys¬ 
tem  will  be  used  for  maintaining  the  master  copy  of  the  design.  Only  cleared 
personnel  have  access  to  the  Moffett-ARC  system. 

As  stipulated  earlier,  all  designing  and  coding  of  KSOS  will  be  done  by 
people  with  at  least  SECRET  clearances.  A  copy  of  the  design  will  be  moved  to 
the  SRI  TOPS-20  system  as  needed.  There,  the  automated  tools  for  design  sup¬ 
port  and  analysis  will  be  applied.  Should  these  tools  discover  design  flaws. 
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the  design  will  be  changed  co  eliminate  them.  The  master  copy  of  the  design 
will  be  kept  at  the  Mof fett-ARC.  All  updates  co  the  design  will  be  made  in  a 
controlled  manner  by  cleared  FACC  personnel.  By  retaining  every  old  master 
copy,  a  complete  secure  audit  trail  of  the  evolving  design  is  assured. 

A  Memorandum  of  Understanding  between  FACC  and  the  Moffett  ARC  will  be 
executed  co  provide  for  services  and  acc.Js  procedures  for  FACC  personnel  to 
the  Moffett-ARC.  This  access  will  provide  secure  storage  for  master  copies  of 
the  KSOS  Specification  sources  chat  were  developed  in  an  unclassified  environ¬ 
ment.  The  procedure  is  designed  to  allow  controlled,  infrequent  access  to 
capes  stored  at  the  ARC  by  FACC  personnel. 

1.  By  standard  clearance  transfer  procedures,  FACC  will  forward  names 
to  ARC  to  establish  an  access  list.  All  personnel  will  be  cleared  for  SECRET 
access.  ARC  will  issue  photographic  identification  badges  to  FACC  personnel 
co  facilitate  base  entry  and  computer  terminal  access  co  the  ARC  PDF-10. 

2.  At  least  24  hours  prior  to  FACC  use  ARC  facilities,  a  ne email  "Use 
Request"  sent  to  ARCSYS(§I-4.  The  "Use  Request"  will  list  the  personnel 
involved,  time  of  use,  serial  numbers  of  capes  co  be  used,  and  mode  of  tape 
use  (read,  write,  deposit,  remove).  This  request  will  be  acknowledged  and 
approver 'denied  by  netmail  to  the  originator  of  the  "Use  Request". 

3.  'apes  at  the  ARC  will  be  scored  in  a  controlled-access  storage  area. 
Each  access  will  be  authorized  by  the  netmail  "Use  Request"  previously  dis¬ 
cussed.  An  access  by  that  lists  authorized  FACC  users  and  contains  each 
approved  use  request  will  serve  to  control  access.  FACC  will  format  the  "Use 
Request"  so  chat  signature  start  time  and  finish  time  are  Indicated.  The  form 
will  then  be  self-prompcing. 

4.  In  addition  co  cape  storage,  the  ARC  will  be  used  co  compare  two 
source  tapes  and  list  differences  between  the  tapes.  The  difference  list  will 
be  used  by  FACC  to  verify  chat  all  differences  between  che  two  tapes  are 
authorized.  The  difference  list  will  be  created  as  a  SECRET-level  document 
and  will  be  sent  from  the  ARC  to  FACC  as  a  controlled  document. 

5.  FACC's  use  of  che  ARC  will  require  ARC  local  terminal  access,  machine 
time  for  installation  and  operation  of  che  file-compare  program,  tape  and  disk 
access,  and  basic  system  familiarization .  Since  the  ARC  has  only  a  single  9- 
track  600  opl  cape  drive,  ARC  will  provide  temporary  disk  storage  co  FACC  to 
hold  working  copies  of  the  capes  to  be  compared.  Controlled  access  storage 
for  no  more  than  cwency-five  10.5  inch  magnetic  tape  reels  is  also  required. 

2.3.  Code  Security 

Changes  co  source  code  under  configuration  control  will  require  explicit 
authorization  by  the  FACC  KSOS  Configuration  Control  Board.  Each  approved 
source  change  will  correspond  to  an  SCCS  DELTA  and  will  be  documented  in  a 
configuration  control  notebook.  The  approved  DELTAS  and  their  supporting  jus¬ 
tification  will  form  an  audit  trail  for  each  controlled  item. 

The  basic  physical  security  for  che  GFE  PDP-11/70  during  implementation 
will  be  in  accordance  with  long  standing,  government-approved  FACC  policies. 
The  implementation  of  KSOS  will  be  done  using  both  the  GFE  PDP-11/70  and 
FACC's  capital  PDP-11/45  UMX*tm  system.  Both  will  be  located  in  secure 


-  14 


WDL-TR7799 


KSOS  Implementation  Plan 


facilities  where  access  by  uncleared  personnel  will  be  restricted.  Primary 
access  to  these  systems  will  be  through  Hardwired  terminals. 

If  and  when  external  (dial-up  or  ARPANET)  communications  lines  are 
enabled,  the  master  copy  of  the  KSOS  software  will  not  be  present.  This  will 
be  done  by  using  a  mountable  file  system,  and  removing  the  disk  when  the  dial 
up  communication  lines  are  enabled.  This  master  pack  will  be  handled  as  if  it 
were  a  SECRET  level  object.  Working  copies  of  the  software  can  continue  to 
remain  on  the  system  during  periods  when  communication  lines  are  enabled, 
since  working  copies  are  Created  as  UNCLASSIFIED.  Conversion  of  working 
copies  to  master  copy  status  requires  the  same  review  process  that  is  used  for 
approving  updates  made  to  the  specifications,  viz,  Configuration  Control  Board 
approval.  FACC  expects  to  utilize  the  UNIX*tm  file  comparison  utilities  for 
these  checks.  Of  course,  only  KSOS  project  personnel  will  be  given  passwords 
on  the  GFE  system  and  only  project  related  work  will  be  carried  out  there. 
These  actions  effectively  prevent  access  to  the  KSOS  implementation  by  any  but 
cleared  personnel  with  a  valid  need  to  know. 

The  effect  of  these  measures  is  that  the  master  copies  of  the  design  and 
implementation  are  completely  protected  at  the  SECRET  level.  There,  an 
uncleared  agent  cannot  systematically  alter  the  design  or  the  tools  to  intro¬ 
duce  security  flaws. 

In  summary,  the  proposed  FACC/SRI  KSOS  design  and  implementation  process 
will  satisfy  all  Government  security  and  control  requirements. 
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3*  Verification  Impact 


3.1.  Source-Level  Configuration  Control 

As  discussed  above,  FACC  plans  to  use  a  source  control  system  similar  to 
thac  provided  by  the  UNIX*tm-based  Programmer's  Workbench  [Ivie  77].  This 
source  control  system  vlll  allow  reconstruction  of  any  level  of  source  code 
(release  and  version),  thus  providing  a  complete  verslon-to-verslon  audit 
trail.  Updating  of  the  master  library  will  be  restricted  to  the  Programming 
Support  Librarian,  who  is  on  the  Implementation  Manager's  staff.  Updates  to 
the  master  development  library  are  entered  only  after  testing  and  approval  by 
the  cognizant  verification  team.  At  any  point  in  time,  any  version  or  release 
of  the  system  can  be  reconstructed  on  demand,  allowing  complete  auditing  of 
all  differences  between  system  versions. 

3.2.  Modification  Request  System 

By  subjecting  all  modification  requests  to  the  same  formal  design  and 
code  inspections  required  for  initial  development,  and  by  using  the  source 
control  system,  FACC  will  ensure  the  same  high  level  of  integrity  throughout 
the  development  cycle.  Subsequent  maintenance  functions  will  build  upon  the 
control  and  request  systems  used  during  development. 

3.3.  Programming  Standards  Enforcement 

Consistent  and  correct  implementation  of  the  proven  design  is  of  utmost 
importance  to  the  success  of  Che  KSOS  project.  The  KSOS  programming  language 
(KPL)  and  the  implementation  style  will  emphasize  Che  development  of  code  in  a 
form  thac  enhances  ultimate  provability.  Although  complete  formal  code  proofs 
will  not  be  undertaken  by  FACC,  an  emphasis  on  simple  (and  traceable)  realiza¬ 
tions  of  the  specification  will  improve  the  probability  of  successful  automa¬ 
tion  of  code  proofs  in  the  future.  As  previously  discussed,  correspondence  of 
che  implemented  system  to  che  formal  specifications  will  be  mandated  and 
enforced  by  formal  inspection  techniques. 

3.3.1.  Formal  Code  Inspection 

The  formal  code  inspection  process  will  serve  to  enforce  programming 
standards.  One  objective  of  these  standards  is  to  provide  che  Government  with 
programs  chat  are  in  a  form  suitable  for  automated  code  verification.  To  this 
end,  FACC  will  use  programming  constructs  that  will  simplify  che  code  proof 
process.  As  an  incidental  benefit,  these  measures  also  make  testing  somewhat 
easier.  Mutual  inclusion  of  test-team  and  implementation-team  members  in  com¬ 
plementary  formal  inspections  helps  to  ensure  good  communication  between  the 
teams.  Scudles  [Larson,  1973,  p.  7]  indicate  significant  savings  in  personnel 
time  (83  percent!)  over  traditional  testing  methods. 

3.3.2.  Production  Coding 

FACC  intends  to  subject  all  designs  and  coding  to  che  formal  inspection 
process.  Inspection  gives  the  highest  practical  level  of  visibility  to  each 
module.  3ecause  inspection  subjects  the  module  to  the  multiple  view-points  of 
cue  inspection  team,  FACC  feels  that  che  code  produced  under  che  formal 
inspection  process  will  meet  uniformly  high  quality  standards. 
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4.  Performance  Impact 

The  design  and  coding  methodology  used  by  FACC  balances  Che  potentially 
conflicting  objectives  of  verifiability  and  performance.  Each  formal  inspec¬ 
tion  will  address  these  issues,  judging  the  design  or  code  in  terms  of  the 
engineering  trade-offs  that  must  be  made.  The  initial  implementation  of  any 
module  will  usually  sacrifice  performance  for  simplicity  and  verifiability. 
If  performance  bottlenecks  are  found  to  exist,  then  internal  redesign  of  the 
module  may  be  necessary.  SRI  International's  Hierarchical  Design  Methodology 
(HDM)  permits  this  type  of  change  by  completely  identifying  the  interfaces. 
As  long  as  the  Interface  is  not  changed,  the  module  may  be  freely  altered,  due 
to  the  transparency  provided  by  the  methodology. 

4.1.  Formal  Code  Inspections 

The  FACC  commitment  to  formal  inspections  is  expected  to  be  a  wise 
investment,  because  the  thorough  review  process  will  expose  programming  errors 
early,  before  testing  is  underway.  FACC  anticipates  that  the  reduction  in 
programming  and  testing  costs  will  more  than  offset  the  Inspection  costs. 

4.1.1.  Algorithm  Review 

One  of  the  functions  of  a  design  code  inspection  is  algorithm  review. 
The  inspection  team  is  required  to  methodically  compare  the  proposed  design 
with  its  controlling  specification.  Incomplete  or  inappropriate  algorithms 
should  be  detected  early  in  the  development  process,  thus  allowing  early 
correction.  The  cost  benefits  of  early  error  detection  and  correction  have 
been  found  to  be  enormous  (ten  to  one  hundred  times  cheaper  to  fix  an  error  in 
design  than  after  delivery.  [Boehm  76])  This  is  one  reason  that  FACC  is 
implementing  the  formal  Inspection  process  at  design  time  and  at  code- 
completion  time  (before  integration  and  testing  begin). 

4.1.2.  Programmer  Productivity 

Various  studies  have  indicated  that  programmers  can  be  significantly  more 
productive  when  programming  teams  can  be  effectively  formed  [Weinberg  71]. 
The  KSOS  project  will  form  a  small  number  of  teams  organized  to  capitalize  on 
special  capabilities  of  the  FACC/SRI  KSOS  project  staff.  To  the  extent  possi¬ 
ble,  staffing  of  teams  will  be  based  on  individual  capabilities  rather  chan 
seniority. 

The  review  time  required  by  the  formal  inspection  program  appears  to  be 
an  excellent  investment.  Studies  by  [Fagan  76]  indicate  that  inspection 
improves  programming  productivity  by  more  than  twenty  percent  in  comparison  to 
coding  subjected  to  structured  walk-throughs  only.  In  addition,  the  inspec¬ 
tion  sample  had  thirty-eight  percent  fewer  errors  during  the  period  between 
unit  test  completion  and  system  test. 

4.2.  Performance  Monitoring 

Measurement  of  dynamic  behavior  of  programs  is  a  necessary  part  of  both 
performance  validation  and  software  testing.  FACC  will  utilize  both  self- 
hosted  and  satellite-processor  based  measurement  techniques. 
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4.2.1.  Self -floated  Measure* 

A  timer-based  program  counter  sampler  will  be  used  ro  measure  performance 
of  programs  ac  the  user  level.  This  facility  will  be  similar  to  the  "profile" 
command  in  UNIX*tm.  It  is  expected  that  timer-baaed  sampling  facilities  will 
also  be  usable  in  measuring  emulator  performance. 

4  2.2.  Satellite  Processor 

In  order  to  avoid  synchronization  artifact  between  the  system  clock  and 
the  program  execution  sampler,  an  external,  independent  sampling  control  is 
necessary.  Whenever  sampling  is  not  Independent  of  system  time,  the  sampler 
is  biased  and  will  not  "see"  certain  events.  Ue  call  this  phenomenon  "syn¬ 
chronization  artifact."  FACC  is  studying  the  feasibility  of  using  a  satellite 
processor  (che  FACC  Software  Development  Facility  machine,  a  PDP-11/45)  to 
provide  remote  stimulation  and  monitoring  through  an  inter-processor  link  made 
from  a  pair  of  DRll-K's.  The  DR11-K  is  a  16-bit  parallel  Interface  similiar 
to  the  DR11-C.  The  DR11-K  acknowledges  data  reads  automatically,  thus  elim¬ 
inating  Che  need  for  software  ACX.  Should  FACC  determine  that  che  necessary 
resources  can  be  committed,  details  of  the  casting  setup  will  be  discussed  in 
che  formal  test  plan. 
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5.  Testing 

Testing  and  verification  are  integral  parts  of  the  development  process. 
Unless  testing  is  carefully  planned,  large  amounts  of  time  can  be  spent 
without  exercising  the  system  adequately.  For  this  reason,  a  logically 
separate  testing  and  maintenance  team  will  be  established  during  Phase  II  of 
the  KSOS  project.  One  function  of  the  formal  reviews  of  design  and  code  is  to 
establish  test  criteria  for  acceptance  of  the  module  for  subsequent  use  in  the 
system. 

Test  cases  are  selected  in  relation  to  the  formal  specifications  such 
that  there  is  at  least  one  test  case  for  the  TRUE  and  FALSE  cases  of  every 
specified  exception  condition,  for  both  x-TRUE  and  x-FALSE  conditions  of  every 
specified  IF  (x)  THEN-ELSE,  for  every  specified  (x)->Q,  and  for  every  possible 
type  of  x  in  every  specified  TTPECASE  (x)  OF  ...  Note  that  testing  is  essen¬ 
tially  negative  in  nature,  since  the  purpose  of  a  test  is  to  find  errors.  A 
test  "failure"  shows  that  no  errors  were  found,  but  can  not  guarantee  the 
absence  of  errors.  A  discussion  of  proposed  verification  and  testing  metho¬ 
dology  is  presented  in  separate  documents,  the  KSOS  Verification  Plan  and  the 
Maintenance  and  Support  Plan. 

5.1.  Module  Tests 

Testing  of  individual  modules  is  the  responsibility  of  the  implementor 
and  the  testing  and  maintenance  team.  As  modules  are  moved  from  development  to 
integration  testing,  the  implementor's  unit  test  results  are  made  a  part  of 
the  Module  Development  Folder  and  are  turned  over  to  the  Test  group.  Modules 
are  recompiled  and  exercised  by  the  Test  group  before  approval  for  inclusion 
in  the  master  source  library.  Wherever  possible,  unit  testing  will  be  carried 
out  within  an  existing  (skeletal)  system  structure  that  has  evolved  from  a 
top-down  hierarchical  design  and  Implementation.  To  the  extent  possible,  con¬ 
tinuous  integration  of  the  system  will  be  carried  out. 

A  minimum  criterion  for  unit  testing  is  to  execute  all  branches  at  least 
once  in  each  direction  except  for  those  branches  representing  defensive  pro¬ 
gramming.  All  Implementation  errors  will  be  corrected  by  source-level  modifi¬ 
cation  in  an  auditable  manner.  No  object-level  code  modification  will  be 
allowed. 

5.2.  Thread  Testing 

Partial  integration  testing  (called  thread  testing  by  FACC)  is  an  attempt 
to  provide  early  integration  of  parts  of  major  systems  functions.  Thread 
testing  is  a  variant  on  top-down  integration  using  module  stubs.  Thread  test¬ 
ing  and  continuous  integration  are  complementary  integration  techniques,  since 
the  notion  of  a  "thread"  is  defined  in  terms  of  a  group  of  related  modules 
that  simulate  the  complete  product  environment.  It  is  this  environment  that 
provides  the  vehicle  for  continuous  integration  testing.  Ultimately,  the 
environment  into  which  a  module  is  being  Integrated  will  be  the  entire  system. 
At  that  point,  continuous  integration  will  evolve  into  system  integration. 
The  key  points  to  remember  are  that  integration  activity  begins  very  early  in 
the  coding  process,  and  chat  Integration  is  a  fundamental  part  of  module 
acceptance  into  system  libraries. 
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Testing  will  reveal  errors  la  the  Implementation  of  the  KSOS  design.  The 
error  source  must  be  traced  so  chat  corresponding  specifications  can  be 
corrected.  For  example,  design  errors  require  formal  specification  changes, 
while  only  HDL  changes  may  be  required  In  ocher  cases.  Simple  programming 
logic  errors  may  require  no  changes  to  the  specifications. 

5.3.  Cumulative  Testing 

Test  cases  for  each  module  will  be  accumulated  for  application  during 
integration  testing  and  for  release  casting  of  an  Integrated  system.  The 
accumulation  of  tests  can  be  run  at  any  time  to  verify  consistent  behavior 
across  releases.  Release-dependent  tests  can  be  handled  through  use  of  the 
SCCS  from  PWB/UNIX*tm. 

5.4.  Required  Testing 

FACC  will  perform  all  applicable  Category  I  and  Category  IX  tests  and 
prepare  the  appropriate  test  reports.  In  addition,  a  comparison  of  KSOS  per¬ 
formance  with  Western  Electric  UNIX*tm  (Distribution  6.0)  will  be  made  using 
the  MITRE  benchmark  scripcs,  along  with  any  ocher  tests  chat  FACC  or  the 
Government  deem  appropriate. 

5.5.  Stress  Testing 

A  common  failure  mode  of  systems  occurs  when  an  apparently  working  system 
Is  exercised  in  a  way  that  forces  resource  exhaustion.  Stress  testing 
actempts  Co  subject  the  system  to  extreme  "pressures"  to  find  areas  of  unac¬ 
ceptable  performance  degradation  or  system  failure.  Such  testing  is  particu¬ 
larly  important  in  KSOS  because  resource  exhaustion  can  be  used  as  a  leakage 
channel.  KSOS  will  utilize  explicit  resource  quotas,  probably  in  the  form  of 
quotas  on  a  per-process  or  per-user  basis- 

While  stress  testing  actempts  to  exercise  the  system  to  the  breaking 
point,  volume  testing  attempts  to  expose  the  system  to  massive  amounts  of  data 
over  an  anticipated  operational  peak  period.  In  the  KSOS  project,  volume 
testing  will  be  used  to  measure  system  performance  for  comparison  with  Wescern 
Electric  Distribution  6.0  UNIX*tm  and  to  estimate  throughput  of  the  system. 

5.5.1.  Shell  Script 

Benchmarks  and  basic  performance  testing  can  be  carried  out  in  a  self- 
hosted  mode  by  means  of  a  UNIX*tm  shell  command  file.  This  can  provide 
(moderately)  biased  timing  estimates  useful  for  basic  system  performance  meas¬ 
urement.  The  MITRE  benchmark  scripts  will  be  used  to  provide  a  comparison 
basis  between  6.0  UNIX*tm  and  KSOS. 

5.5.2.  Externally  Generated  Load 

Use  of  the  FACC  Software  Development  UNIX*cm  system  as  an  external  load 
generator  will  provide  a  terminal  simulator  for  stress  and  volume  testing  of 
the  KSOS  system.  Response  time  and  throughput  statistics  can  be  gathered  by 
the  external  computer  system  without  introducing  timing  artifact  into  the  KSOS 
system. 
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6.  External  Configuration  Management 


6.1.  Supported  Configurations 

KSOS  configuration  support  will  be  limited  to  systems  that  contain  only 
the  equipment  present  in  the  GFE  FDP-11/70  provided  for  Phase  II  development 
system.  Possible  exceptions  to  this  restriction  will  be  in  cases  where  multi¬ 
ple  peripheral  units  are  supported  by  a  single  controller  (e.g.,  multiple  TU16 
tape  transports,  multiple  RP05  disk  drives,  etc.). 

6.2.  Automated  System  Generation 

Manual  generation  of  systems  of  variable  configuration  is  too  error-prone 
to  provide  the  confidence-level  necessary  for  production  release  of  KSOS.  One 
simple  approach  to  the  configuration  problem  requires  that  identical 
(software)  systems  be  delivered  to  all  sites,  with  system  initialization  code 
responsible  for  disabling  code  for  all  missing  control  units. 

At  the  present  time,  FACC  favors  a  system-build  dialogue  that  causes  the 
interrupt  vectors  and  device  tables  to  be  built  automatically.  The  loaded 
system  can  then  contain  only  the  necessary  device  drivers,  giving  more  storage 
to  the  user  programs.  The  major  technical  factor  involved  in  this  approach  is 
concerned  with  proof  that  a  secure  system  that  has  less  peripheral  storage 
than  the  originally  certified  system  is  still  certifiably  secure.  FACC  will 
use  a  system  structure  chat  ensures  the  certlf lability  of  subset  systems. 

6.3.  Secure  Delivery  and  Installation 

Since  KSOS  is  expected  to  have  wide-spread  usage,  secure  logistics  must 
be  implemented.  With  an  automated  system  generation  facility,  it  appears  rea¬ 
sonable  to  send  a  self-starting  generation  system  (at  the  SECRET  level)  by 
U.S,  mall.  Under  separate  cover,  at  appropriate  security  levels,  a  generation 
script,  documentation,  a  password,  and  system-tape  check-sums  would  be  for¬ 
warded.  The  initially  booted  system  contains  a  tape  validity  check  program,  an 
authentication  program,  and  a  KSOS  system  build  restorer.  The  actual  instal¬ 
lation  process  must  be  carried  out  at  the  "system-high"  classification  level, 
the  highest  classification  level  that  the  system  will  ever  process.  Further 
discussion  of  the  installation  process  is  given  in  the  Support  and  Maintenance 
Plan. 


6. A.  Maintenance  and  Support 

The  necessity  for  reverifying  KSOS  whenever  any  changes  are  made  to  the 
system  requires  that  stringent  configuration  control  be  exercised.  KSOS  will 
not  be  a  static  system,  since  new  devices  will  need  to  be  interfaced  to  it, 
enhancements  to  its  operation  will  certainly  be  suggested,  and  implementation 
errors  may  be  discovered.  Thus  FACC  will  develop  a  formal  system  for  intro¬ 
ducing  certified  changes  to  KSOS. 

The  companion  Maintenance  and  Support  Plan  addresses: 

a.  A  system  for  implementation  of  enhancements  to  KSOS 

b.  A  method  for  control  and  distribution  of  new  versions  and  updates  to 
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KSOS. 

c.  A  system  security  standard  for  secure  operation  and  maintenance  of  KSOS 
systems. 
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This  Appendix  documents  the  FACC  HDL  processor  and  gives  an  example  of 
its  use* 
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HDL (I) 


NAME 

hdl  -  hierarchial  design  language 
SYNOPSIS 

hdl  I-ficl21pug]  [-d  dname]  [-m  mname]  (-r  rflle]  hdl  files 
DESCRIPTION 

Hdl  is  a  cool  Chat  allows  one  Co  describe  a  projecc,  sysCem  or  module  in 
English,  using  che  higher  level  language  C's  control  flow,  Hdl  provides 
a  verbal  flow  chare  (Che  hdl  source),  a  trace  of  che  static  call  struc¬ 
ture,  an  index  into  the  hdl  source  to  where  procedures,  globals  and  unde¬ 
fined  procedures  are  used,  and  an  index  by  page  number  to  all  the  pro¬ 
cedures  and  hdl  segments. 

Hdl  provides  the  following  defaults.  The  hdl  source  is  reproduced  in  che 
same  format  as  it  was  input.  Output  format  2,  for  short  procedure  and 
global  names,  is  used  to  produce  all  hdl  index  tables.  All  output  is  for¬ 
matted  for  the  printer.  The  last  and  only  critical  default  is  that  unless 
otherwise  informed  through  the  use  of  the  m  flag,  hdl  will  assume  the 
presence  of  the  top  level  procedure  main. 

-f  Keep  che  procedure  and  global  names  on  files  instead  of  in 

core.  This  allow  one  to  process  very  large  hdls. 


Input  Specifiers 

-d  dname  Place  the  design  title  dname  in  the  page  header,  which  is 
printed  at  the  top  of  each  page.  The  design  title  is  limited  to 
a  maximum  length  of  40  characters. 

-m  mname  Use  mname  as  the  top  level  procedure  of  the  hdl. 

-r  rflle  Read  che  file  rfile  to  obtain  the  names  of  Che  hdl  source 
files. 


Output  Specifiers 

-i  Indent  the  hdl  source  to  reflect  the  hdl  control  flow. 

-c  Format  che  output  for  Che  crt.  Note  Chat  the  page  size  has  been 

set  to  be  compatible  with  the  re  (rand)  editor.  This  editor  al¬ 
lows  one  to  examine  a  file  by  page  addressing. 

-1  Format  che  index  tables  to  accommodate  long  procedure  and  glo¬ 

bal  names. 

-2  Format  che  index  tables  to  accommodate  short  procedure  and  glo¬ 

bal  names.  If  output  is  to  be  formatted  for  the  crt  procedure 
and  global  names  should  be  shorter  than  20  characters,  other¬ 
wise  names  should  be  shorter  chan  32  characters.  Note  chat  for¬ 
mat  2  will  accommodate  longer  names.  It  may  however,  page  the 
output  Incorrectly. 
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Output  Suppression  Specifiers 
-1  Suppress  printing  of  the  hdl  source. 

-p  Suppress  printing  of  the  procedure  index  table* 

-g  Suppress  printing  of  the  global  index  table* 

-u  Suppress  printing  of  the  undefined  procedure  index  cable. 

FILES 

/tap /hdl??? 

/usr/sys/source/util/hdl 
/usr/bin/hdl 

/usr/sys/source/util/hdl/hdl_doe 

SEE  ALSO 

indent  (I) 

d  (I)  Automatic  indentation  during  input  (ac  mode), 
re  (I) 

DIAGNOSTICS 

Syntax  errors  are  reported.  They  normally  involve  unbalanced  double 
quotes,  parentheses  or  curly  brackecs. 

BUGS 

Hdl  does  not  support  pure  C  syntax.  See  hdl_doc  for  syntactical 
anomalies . 


tempo raries 
source  files 
executable  file 
documentation  file 
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HDL:  HIERARCHICAL  DESIGN  LANGUAGE 


HDL  is  a  design  tool  that  allows  one  to  describe  a  project,  system  or 
module  in  English,  using  the  structured  constructs  of  the  C  programming 
language.  HDL  provides  a  verbal  type  of  flowchart  with  the  added  pluses  of 
cross-referencing  and  easy  modification. 


HDL  produces  the  following  outputs. 

An  Indented  listing  of  the  source.  All  lines  within  a  procedure  will  be 
numbered  to  the  left  of  the  source.  If  an  elsewhere  defined  procedure  is  used, 
the  page  number  where  that  procedure  is  defined  will  be  placed  to  the  left  of 
the  procedure  line  numbers. 

A  crace  of  the  static  procedure  call  structure.  Note  that  unless  other¬ 
wise  informed  through  the  use  of  the  m  flag,  HDL  will  assume  the  presence  of 
the  top  level  procedure  "main". 

An  index  into  the  HDL  source  to  where  procedures .globals,  and  undefined 
procedures  were  used. 

An  index  by  page  number  to  all  the  procedures  and  HDL  segments. 


Output  from  HDL  may  be  formatted  for  the  printer  or  the  crt.  The  crt 
format  has  been  so  constructed  to  be  convenient  to  be  viewed  on  line  using  the 
re  (rand)  editor.  Since  the  rand  editor  can  view  a  file  by  page  addressing, 
one  can  send  the  last  segment  of  the  HDL  output,  the  HDL  index,  to  the  printer 
and  use  the  HDL  index  to  find  the  desired  segment. 

Those  familiar  with  C  syntax  may  skip  the  following  syntax  discussion. 
However  please  read  the  section  entitled  special  syntax  notes. 


HDL  Syntax  and  Control  Statements 


Basic  syntax  vocabulary: 

ldentifer:  can  be  any  combination  of  letters,  digits  and  underscore  up  to  a 
length  of  60  characters.  The  first  character  must  be  a  letter. 

string:  is  any  text  enclosed  in  double  quotes.  Special  care  should  be  taken  to 
make  sure  that  all  double  quotes  are  balanced  or  an  HDL  error  will 
occur. 

expression:  when  evaluated  becomes  a  value.  The  expression  may  be  text  or 
mathematical. 

conditional:  when  evaluated  becomes  a  value  TRUE  or  FALSE.  Note  as  a  matter  of 
convention  if  the  conditional  is  numeric,  a  non-zero  value  will  be 
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taken  as  TRITE  and  a  zero  value  as  FALSE. 

sentence : any  sequence  of  characters  with  neither  parentheses  nor  unbalanced 
strings  present. 


HDL: 

procedure  deflnltlon>  <statement>  | 

<global  deflnltlon>  | 

<HDL> 

global  definition: 

<ldentlf iers 

procedure  definition: 

<identifier>  (  <sentence>  )  <complex  statements 

Note  that  the  procedure  definition  cannot  be  terminated  with  a  sem¬ 
icolon.  Procedure  definitions  cannot  be  nested,  i.e.,  defined  within 
ocher  procedures. 

statement: 

<sentence>  ;  | 

<complex  statements  1 
<procedure  references  | 

<for  statements  | 

<while  statements  | 

<do  statements  | 

<if  statements  ( 

<awitch  statements  | 

< labeled  statements  | 

<gotos  I 
<breaks  | 

<continues  | 

<recurn  statements 


complex  statement: 

{  Statement  list  s  > 

statement  list: 

statements  | 

Statement  lists 


procedure  reference: 

<ldenclfers  (  <  sentences  ); 

for  statement: 

for  (  <lnitiallzacions  ;  <conditionals  ;  <incrementacions  ) 

<scacemencs  | 

for  (  sentences  ) 

Statements 

forml:  The  initialization  is  performed  once.  The  conditional  is  Chen 
tested.  If  true  the  following  is  performed  until  the  conditional  is 
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false.  The  statement  is  executed,  the  incrementation  Is  performed  and 
the  conditional  is  tested  again. 

form2:  The  statement  is  executed  until  the  task  the  sentence  describes 
is  completed. 


while  statement: 

while  (  <conditional>  )  <statement> 


The  statement  is  executed  repeatedly  as  long  as 
the  conditional  is  true. 

do  statement: 

do  <statement>  while  (  <condltional>  ); 

The  statement  is  executed  then  the  conditional  is  tested.  If  true,  the 
statement  will  be  executed  until  the  the  conditional  is  false. 

if  statement: 

if  (  <conditional>  )  <statement>  i 

if  (  <conditlonal>  )  <statement  1>  else  statement  2> 


Form  1:  If  the  conditional  is  true,  the  statement  is  executed. 

Form  2:  If  the  conditional  is  true,  statement  l  is  executed,  then  con¬ 
trol  is  passed  to  the  first  statement  following  the  if  statement.  If 
the  conditional  is  false,  then  statement  2  is  executed  and  control  is 
passed  to  the  first  statement  following  the  if  statement. 


switch  statement:  Is  a  clear  way  to  express  a  nested  group  of  if  else  state¬ 
ments.  Its  syntax  is  described  in  the  following  three  productions. 


switch  statement: 

switch  (  Expression?  )  <case  statement  list> 

case  statement  list: 

<case  statement  | 

<case  statement?  <case  statement  list? 

case  statement: 

<statement?  | 

case  Expression?  :  otatement?  | 
default  :  Otatement?  j 
break; 


The  following  is  an  example  of  a  switch  statement, 
switch  (  Expression  0?  ) 

{ 

case  Expression  1?  :  otatement  1.1? 
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<statemenc  1.2> 
break; 

case  Expression  2>  : 

casa  Expression  3>  :  <scacemant  3.1> 

case  <expression  4>  :  otatemenc  4.1> 

break; 

case  default: 

Etatement  d.l> 
<scaceaenc  d.2> 


The  control  flow  for  the  switch  statement  is  as  follows.  Expression 
zero  is  evaluated.  Then  the  expressions  following  the  word  case  are 
evaluated  in  order.  When  the  first  expression  equal  to  expression  0  is 
found,  control  is  passed  to  the  statements  following  the  colon.  The 
control  flow  will  pass  from  one  statement  to  the  next,  ignoring  case 
expression  labels,  until  a  break  or  the  and  of  the  switch  is  encoun¬ 
tered.  A  break  statement  passes  control  to  the  first  statement  after 
the  switch  statement. 

Note  that  if  none  of  the  case  expressions  equal  expression  0,  control 
will  pass  to  the  statements  following  the  default  case  label  if  it  is 
prasenc,  otherwise  control  will  pass  to  the  statement  following  the 
switch  statement. 


Special  statements: 
break:  break; 

This  statement  terminates  the  smallest  enclosing  while,  do,  for  or 
switch  statement.  Control  is  Chen  passed  to  the  statement  following 
the  terminated  statement. 


continue:  continue; 


This  statement  passes  control  to  the  loop-continuation  portion  of  the 
smallest  enclosing  while,  do,  or  for  statement.  For  example: 


while  (...) 

( 

a  a  e 

concln:  ; 

> 

A  continue  statement  in  any  of  these  loops 
meat : 

goto  concln; 


do 

( 


concln: ; 


f or ( . . . ) 

( 

see 

concln: ; 

> 

is  equivalent  to  the  state- 


labeled  statement :  <identifler>  :  <scatament> 

Any  statement  may  be  preceded  by  a  label.  However  labels  make  for 
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poorly  scrucCured  and  difficult  to  understand  HDL's.  They,  therefore 
should  be  avoided  at  (all  -  1)  costs* 

goto:  goto  <identlf ler>; 

This  statement  passes  control  to  the  statement  preceded  by  the  label 
indentifler. 


return  statement: 

return; 

return  (  <expression>  ); 

The  return  statement  terminates  the  present  procedure,  control  is  then 
passed  to  the  calling  procedure*  Note  that,  if  necessary,  a  value  can 
be  returned  to  the  calling  procedure. 


Special  syntax  notes: 

Parentheses  are  used  for  procedure  definitions  and  references.  They, 
therefore,  cannot  be  used  for  any  other  purpose  within  an  HDL.  The 
user  has  two  options  for  grouping  a  thought,  some  delimiter  such  as 
square  brackets  could  be  used  instead  of  parentheses,  or  the 
parenthesized  sentence  could  be  enclosed  in  double  quotes. 

HDL  scans,  that  is,  does  not  parse,  the  HDL  source.  For  this  reason 
the  left  parenthesis  of  a  procedure  definition  or  reference  must  occur 
on  the  same  line  as  the  procedure  name.  A  left  parenthesis  on  any 
given  line  must  always  be  preceded  by  an  identifer. 
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HDL  PROCEDURES 


PROCEDURE:  main 


3 


5 

I 

| 


1 

2 

3 

4 

5 

6 
7 
S 
9 

10 

11 

12 

13 

14 

15 

16 
17 


main  ( ) 

/*  DESCRIPTION:  This  procedure  will  construct  the  static  call 
structure  of  the  procedures  thac  it  is  given  as  input  */ 

{ 

Invoke  cref  to  process  the  input  procedures  and  produce  a 
temporary  output  file; 

Construcc_the_list_of_procedures  () ; 

Make_procedure_branch^_array  ( ) ; 

Construct_the_static_call_tree  () ; 

Print  the  call  tree  (); 

> 


I  LINE  NUMBER  IN  PRESENT  PROCEDURE 

I 

REFERENCE  TO  A  PROCEDURE  DEFINED  ON  PACE  5 


FACC/WDL  Design  1 

DEFINED  GLOBALS 

GLOBALS 


Dec  6  1977  Page  2 


int  buffer J256J ; 
lnt  node ; 


IDENTIFIER  TYPING 
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1 

2 

3 

4 

5 

6 
7 
3 
9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 


HDL  PROCEDURES 

Cons true t_che_l  is t_of_p r ocedurea 
Construct_the_list_of_procedures  () 

< 

Open  the  cref  temporary  output  file; 

get_line  (character  buffer); 

First_string  -  get_first_string__ from_line  (); 

Second__string  ■  get  seconds  trine  from  line  (); 

while  (not  end  of  file) 

{ 

if  (Second  string  is  a  then  first  string  is  a  global) 

{ 

Allocate  a  node; 

Fill  a  node  with  characters  pointed  to  by  First__string; 
Link,  this  node  to  first  node  of  the  procedure  branch 
array; 

> 

else 

( 

if  (First  string  is  in  the  list  of  procedures  ()  ) 

{ 

if  (First_string  is  a  new  procedure) 

< 

Fill  the  present  procedure  with  the  Firat_str ing ; 
Allocate  a  new  branch  and  node; 

Link  the  end  of  the  branch  array  branch- >next_branc 
to  the  new  branch; 

Link  the  braneh->pointer_to_node  to  the  node  just 
allocated; 

Make  node->pointer_to_node_naae  point  to  the  name 
of  the  procedure  in  the  procedure  array; 

> 

else 

{ 

Allocate  another  node; 

Make  the  node->pointer_to_node_name  point  to  the 
name  in  the  procedure  array; 

if  (if  the  present  procedure  is  the  first  son 
in  this  branch  ) 

Link  the  present  node  to  the  last  node's 
node->pointer_to_son ; 

else 

Link  the  present  node  to  the  last  node's 
node->pointer  to  brother; 

> 

} 

> 

get_llne  (character  buffer); 

Flrst_string  •  gec— f irst_string__f rom_line  (); 
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55 

56 

57 

58 

59 


Cons true t_the_list_of_procedures 

Second  string  -  gee  second  string  from  line  (); 

> 

return  (pointer  to  the  first  element  of  the  list) ; 
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5 


5 


5 


1 

2 

3 
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9 
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12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 
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39 
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41 

42 

43 

44 

45 

46 

47 


Construct_the_static_call_tree  (pointer  to  branch  array,  pointer  to  node  ) 


if  (Check._if_node_is_recursive  (pointer  to  the  node)  ) 

{ 

Add_a_blank_s  tar_to_the_end_of_the_procedure_name  (pointer 
to  the  node); 

Set  the  node's  node->pointer_to_son  to  NIL;  That  is  don't 
allow  the  node  to  adopt  his  sons; 

if  (the  node->pointer_to_brother  is  not  NIL) 

< 

Construct_the_static_call_tree  (branch  array, 
node->pointer_to_brother  ); 

> 

> 

else 

{ 

C he c lc_b r an c h_a r r a y_and_r e t u r n_a_p o in t e r_t o_t he_no d e_s_s on  ( 
pointer  to  the  branch  array,  pointer  to  node); 
if  (the  pointer  returned  is  equal  to  NIL) 

{ 

Set  pointer  to  node->pointer  to  son  to  NIL; 

> 

else 

( 

Set  present  node->pointer_to_son  to  point  at  this 
node's  sons; 

if  (the  node->pointer_to_son  is  not  equal  to  NIL) 

{ 

push_procedure_on_active_procedure_stack  (node) ; 

Construct_the_static_call_tree  (  pointer  to  the 
branch  array,  node->pointer_to_son) ; 

pop  ac? ive_procedure_stack  (); 

> 

> 

if  (node->pointer_to  son  is  not  equal  to  NIL) 

{ 

Construct_the_static_call_tree  (pointer  to  the  branch 
array,  node->pointer_to  brother); 

> 

> 

> 
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main 


Construct_che_list_of_procedures 
Cons  true  c_che_s  ta  t  ic_cal  l_tr  ee 

Construct_the_s  tatic_call_tree 
Cons  truct_the_s  tat ic_call_tree 
Construct  the  static  call  tree 
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PROCEDURES 

3  Cons t rue t_che_list_of_procedures 
called  by: 

1  main 

at  line(s):  10 

5  Construct_the_static_call_tree 
I  called  by: 

I  5  Cons  true  t_the_static_call_tree 

I  at  line(s):  14  35  43 

I  1  main 

I  I  at  line(s):  14 

I  I  i 

|  I  LINE  NUMBER  IN  main  WHERE 

|  |  consruct_the_static_call_tree 

I  I  IS  CALLED. 

I  I 

I  PAGE  NUMBER  WHERE  main 

I  IS  DEFINED. 

I 

PAGE  NUMBER  WHERE 
Construct_the_static_call_tree 
IS  DEFINED. 


FACC/WDL  Design  1  Dec  6  1977  Page  8 

INDEX  To  GLOBALS 

GLOBALS 


buffer 

referenced  by: 

3  Const rue t_the_list_of_procedures 
at  line(s):  52  6 


node 

referenced  by: 

3  Cons true t_the_list_of_procedures 


at  line(s):  15 

16 

17 

17 

28 

31 

33 

38 

39 

44 

44 

45 

47 

47 

48 

Const rue t_the_static_ 

call  tree 

at  line(s):  10 

*12 

15 

21 

24 

28 

29 

31 

33 

36 

4 

41 

44 

7 

9 

9 
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INDEX  To  UNDEFINED  PROCEDURES 
UNDEFINED  PROCEDURES 

Add_a_blank_star_co_che_end_of— che_proeedure_uame 
called  by: 

5  Construct_>the_static_call_tree 
at  line(s):  6 

Ch  ec  k_b  r  an  c  h_a  r  r  ay_and_r  e  tu  r  n_a_p  o  in  e  e  r_t  o_C  he_node_s 
called  by: 

5  Conatruct_the_staeic_call_tree 
at  line(s):  20~ 

Check_if_node_is_recur  sive 
called  by : 

5  ConstrucC_che_stacic_call_tree 
ac  line(s):  4 

Firsc_scring_is_in_che_list_pf_procedures 
called  by: 

3  Cons  true  C__the_lisc_of procedures 
ac  line(s):  22 

Make_procedure_branch_array 
called  by: 

1  main 

at  line(s) :  12 

Pr  in  t_che_cal  l_c  r  ee 
called  by: 

1  main 

ac  line(s):  16 

ge  c_f  i  r  s  c_s  t  r  ing_£  r  om_l  ine 
called  by: 

3  Cons trucc_che_list_of_jrocedures 
ac  line(s):  54  8 

gec_line 

called  by: 

3  Cons  true  t__che_lisc_of_procedures 
ac  line(s):  52  6 

ge  c_sec  ond_s  cr  ing_f  r  om_line 
called  by: 

3  Cons  trucc__che_ll3t_of_jrocedures 
ac  ltne(s):  55  9 

pop_accive  _procedure_scack 
called  by: 

5  Conscruce__che_stacic_call_eree 
ac  line(s):  38 


son 
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push_procedure_on_active_procedure_stacR 
called  by: 

5  Construct_the_static_call_tree 
ac  line(s):  33 
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Appendix  discusses  programming  standards  for  use  with  C-language 
It  is  a  prototype  of  the  standards  to  be  used  with  the  KSOS  pro¬ 
language. 
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UNIX  Coding  Guidelines 


Ford  Aerospace  &  Communications  Corporation 
Western  Development  Laboratories 
Software  Technology  Department 
3939  Fabian  Way 
Palo  Alto,  California  94303 

ABSTRACT 


This  paper  presents  guidelines  and  standards  for  C  language 
programmers  in  the  writing  of  C  programs  for  UNIX.  The  rationale 
is  to  provide  a  minimum  level  of  coding  quality  so  that  programs 
are  easy  to  read,  understand  and  support. 


1.  General  Rules 

Comments  should  be  used  freely.  Remember  that  a  comment  should  explain 
what  is  happening.  Comments  which  state  the  obvious  are  a  waste  of  time. 
Blank  space  and  blank  lines  make  code  easier  to  read.  A  blank  line  should 
separate  sections  of  code  and  declarations  from  statements.  Programs  should 
be  made  into  small  modules  of  one  or  two  pages  except  in  cases  where  the  code 
is  long  but  sequential.  Wherever  possible,  functions/procedures  should  be 
less  than  one  page  long. 

1.1.  Identification  Information 

Each  program  or  function  must  have  a  preamble  in  the  form  of  a  comment 
containing  the  following  information: 

*  /* 

*  Name:  name  of  module,  program  or  function 

*  Function:  purpose  of  module.  General  functional  description  of  what  the 
module  does. 

*  Algorithm:  detailed  description  of  how  the  program  or  module  accom¬ 
plishes  its  task.  May  refer  to  another  document  if  the  algorithm  is 
very  technical. 

*  Parameters:  list  of  the  names,  meanings,  and  values  of  all  parameters 
used  to  invoke  the  function.  If  a  main  program,  a  list  of  the  arguments 
and  options  and  their  meanings. 

*  Returns:  if  a  function,  the  type  and  meaning  of  any  return  values.  If  a 
main  program,  the  meaning  of  any  exit  codes. 

*  Globals:  a  list  of  all  global  variables  used. 

*  Calls:  a  list  of  all  functions  invoked  by  this  program  including  a  list 
of  all  system  calls  made. 

*  Called  by:  a  list  of  all  (known)  functions  that  invoke  this  function. 
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*  Flies  and  Programs:  a  Use  of  all  flies  used  by  chis  program  (ocher  chan 
chose  passed  in  via  Che  argumenc  lise).  A  Use  of  all  programs  called  by 
chis  module  via  che  exec  syscem  call* 

*  Notes  and  memorabilia:  informacion  noc  Incuicively  obvious  co  che  gen¬ 
eral  programmer.  Program  bugs,  deficiencies  and/or  special  feacures. 
Warnings  on  inscallaclon  problems  chaC  may  result.  Syscem  dependencies 
(for  example,  assumes  Version  7  of  che  C  compiler). 

*  Installation  instructions:  details  on  how  to  compile  Che  program.  This 
should  be  a  sec  of  UNIX  commands.  Also,  names  of  any  ocher  library 
routines,  etc. 

*  History:  dace  of  coding  and  author  version  number.  This  will  be  fol¬ 
lowed  by  an  entry  for  each  change. 

1.2.  Configuration  Information 

Each  separately  compiled  module  should  have  an  embedded  string  with  con¬ 
figuration  informacion.  Such  a  facility  is  available  using  the  key  word 
feacures  of  the  Source  Code  Control  Syscem  of  Programmer's  Workbench.  This 
string  contains  a  set  of  four  special  characters  that  are  very  unlikely  to 
appear  in  any  normal  situation.  They  are  followed  by  the  configuration  infor¬ 
mation.  Sample  strings  are: 

char  ftp_id[]  UNIX  Server  FTP  Version  1.3"; 

char  idC]  "~l"'  main.c  1.3"; 

All  library  modules  loaded  with  the  program  should  also  have  such  a  configura¬ 
tion  line  whenever  the  module  is  not  a  standard  module.  Programmer's  Work¬ 
bench  has  a  program  named  "what"  that  extracts  Chis  information  from  a  file  or 
files. 


1.3.  Release  History 

For  each  version  or  release  of  the  software  module  a  line  must  occur  in 
che  preamble  giving  the  following  Information: 

*  version/release 

*  author/modif ier 

*  dace  of  change 

*  history  or  reason  for  change. 

1.4.  Use  che  C  Pre-Processor 

The  C  pre-processor  should  be  used  to  assist  che  reader.  Use  che  //define 
feature  whenever  there  are  manifest  constants,  strings,  and  data  structures. 

1.4.1.  Data  Structure  Definitions 

All  standard  data  structures  should  be  defined  by  use  of  an  include 
statement.  General  syscem  data  structures  should  all  be  defined  by  the  same 
file.  A  common  library  of  definitions,  data  structures  and  file  names  should 
be  maintained.  Data  structure  and  field  names  should  be  Che  same  as  chose 
specified  in  che  UNIX  Programmer's  Reference  Manual.  Don'c  use  the  field  name 
fd  when  che  manual  calls  it  fildes. 
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1.4.2.  Conditional  Compilations 

Use  the  conditional  compilation  feature  to  Include  debug  statements.  Use 
it  to  allow  custom  or  installation  dependent  features.  For  example,  if  your 
installation  favors  Che  use  of  the  program  "dir”  to  obtain  directory  listings 
instead  of  the  old  reliable  "Is",  use  a  conditional  compile: 

#ifdef  CAC 

execl  ("/bin/dir", "dir", arg, 0) ; 

else 

execl  ("/bin/ls", "Is", "-l",arg, 0) ; 

//end  if 


1.4.3.  Embedded  Strings 

The  software  should  not  contain  strings  which  have  embedded  file  names; 
login  names  ocher  than  root  or  bln;  program  names;  etc.  If  any  of  these 
strings  are  required,  they  should  be  declared  as  defines  or  includes  at  the 
head  of  the  module  Immediately  following  the  preamble  and 
conf iguration/ldencif lcation  string.  For  example,  use  the  following: 

//define  PASSWD  "/etc/passwd" 
fd  -  open (PASSWD, 0) ; 
and  not 

fd  -  open  (M/etc/passwd",0) ; 

1.4.4.  Manifest  Constants 

Manifest  constants  should  be  specified  as  parameters,  e.g., 
while (  a  !-  EOF  )  ... 
and  not 

while (  a  !»  0)  ... 

and 

while  (TRUE) 
instead  of 
while (1 ) 

System  constants  (e.g.,  512,  16)  should  be  specified  by  the  compiler  construct 
sizeof  or  parameterized  as  BLKSIZ. 

count  »  read(dirfile,4dirent, sizeof  dirent) ; 

NOT 

count  -  read(dirfile,6dirent, 16) ; 

1.5.  Error  Messages 

Messages  printed  by  the  program  should  be  specified  as  constant  scrings 
declared  at  the  head  of  the  program  or  module,  or  as  Include  files. 

Error  messages  should  be  of  Che  form 

<program>  :  <file  name>  :  <diagnostic>  (  <messages  number>  )  For  example, 
delta:sam.c:wrice  error(203) 

Error  numbers  should  be  assigned  centrally.  For  each  error  number  a 
short  (1  to  5  line)  explanation  should  be  provided  giving  information  on  what 
che  message  means,  corrective  action  to  be  taken  by  Che  user,  etc.  This  can 
be  integrated  into  the  users  manual  or  installed  into  a  help  file. 


Programming  Standards 


-  B-3 


WDL-TR7799 


KS OS  Implementation  Plan 


1-6.  Enclosing  Braces 

Each  bracketing  pair  (the  pair  of  braces  and  ">")  should  be  identi¬ 
fied  if  they  are  separated  by  more  than  a  few  lines.  Examples: 

>  /*  main  */ 

and, 

>  /*  switch (*cp)  */ 

and, 

}  /*  f or (i»l ; ...  */ 

1.7.  Null  Statements 

Null  statements  should  be  specified  as  deliberate  by  placing  the  on  a 
separate  line.  Thus, 

while(  (c»getchar () )  !»  ',')  ;  /*  consume  input  line  to  next  comma 

V 

specifies  the  intent  clearly. 

1.8.  Position  Critical  Code 

Code  or  declarations  which  are  position  dependent,  or  cannot  have  inter¬ 
vening  code  inserted  must  be  designated.  Avoidance  of  these  constructs  is 
better  yeti 

1.9.  Function  References 

References  to  functions  returning  values  other  than  integers  and  refer¬ 
ences  to  external  variables  used  as  constants  in  initializatin  of  data  struc¬ 
tures  must  be  declared  (via  extern)  prior  to  use.  All  side  effects  of  func¬ 
tion  references  must  be  documented. 


2.  Beauty 

All  programs  should  be  processed  by  the  standard  indenter  (indent)  before 
release.  This  will  ensure  compliance  with  installation  standards. 

2.1.  Line  Length 

Lines  longer  than  72  characters  are  in  bad  taste.  CRT  oriented  editors 
have  problems  with  them.  Also,  it  is  hard  to  print  the  program  on  8  1/2  by  11 
paper  for  binding. 

2.2.  Major  Comments 

Comment  blocks  of  any  length  should  be  distinguished  as  follows: 

/* 

*  Place  a  line  of  stars  as  shown.  Indent  or  tab 

*  for  the  body  of  the  comment.  Be  sure  to  end  the 
"  line  of  stars  with  the  appropriate  ending  (*/) 

*/ 

The  major  reasons  are 

*  to  maxe  major  comments  obvious  and  readable, 

*  to  prevent  the  loss  of  an  end  comment  by  it  having  too  far  from  the 
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start, 

*  and  to  prevent  a  person  from  adding  a  line  to  the  comment  in  such  a  way 
as  to  end  the  comment  unintentionally* 


3*  Expressions  and  Operators 

All  operators  involving  the  equal  sign  (“)  should  be  separated  by  blanks 
to  prevenc  ambiguous  code*  I*e*,  this 
a  ■  *b; 
a  ■  -b ; 
a  —  b; 
a  “  b ; 
and  not 
a-*b; 
a~-b ; 
a«"b ; 

Surrounding  arithmetic  and  logical  operators  with  blanks  Improves  code  reada¬ 
bility  considerably. 


4.  Summary 

The  most  ingenious  coding  is  of  no  value  if  people  other  than  the  writer 
of  the  code  cannot  read  and  understand  it.  The  above  guidelines  suggest  how 
to  write  C  programs  so  other  people  will  find  it  easier  to  read  and  maintain 
them.  There  is  value  in  following  guidelines  in  that  the  programs  will  be 
easier  to  understand  and  modify. 
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Programming  development  tools  discussed  in  this  Appendix  will  be  used  to 
support  the  KSOS  programming  process*  When  the  KSOS  programming  language 
(KPL)  is  determined,  comparable  facilities  will  be  developed  to  support  KPL 
development*  Programs  discussed  In  this  Appendix  are: 
d  -  the  program  creation  editor 
hdl  -  the  hierarchical  design  language 
indent  -  the  C-indenter 
nn  -  the  procedure  calling  tree  lister 
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NAME 

d  -  Enhanced  UNIX  ed  editor. 

SYNOPSIS 

d  [-]  [name] 

DESCRIPTION 

The  following  is  a  list  of  differences  between  'enhanced'  editor  (from 

UCLA,  UCB,  CAC  and  NPS)  and  the  standard  UNIX  editor. 

1)  Interline  editing:  The  interline  edit  mode  is  invoked  with  the  command 

o  (for  'open').  This  opens  a  line  for  interline  editing.  At  that  point. 

The  following  commands  can  be  used: 

(Space)  Moves  the  cursor  1  ahead  in  the  line,  and  prints  the  character. 

It  Moves  the  cursor  1  back  in  the  line,  and  prints  the  character 

passed  over.  NOTE:  Characters  which  have  been  backspaced  over  and 
characters  which  have  been  deleted  are  shown  between  found  signs 
('#')  to  indicate  that  they  do  not  form  part  of  the  final  line. 

D  or  ~A  Deletes  the  next  character  in  the  line. 

~H  Deletes  the  next  character  in  the  line,  and  backspaces  to  correct 

position  on  print  line. 

e  Deletes  the  previous  character  in  the  line. 

c  Substitutes  the  character  typed  after  it  for  the  next  character 

in  the  line  (may  be  aborted  by  typing  a  ~D) 

s(char)  Does  the  equivalent  of  (space)  until  the  next  (space)  would  print 
che  specified  (char).  It  always  skips  at  least  one  space.  If  the 
specified  (char)  is  not  found,  the  cursor  is  left  at  the  end  of  the 
line. 

k(char)  Like  s,  but  does  the  equivalent  of  a  d  command.  If  the  specified 
character  is  not  found,  the  cursor  is  not  moved. 

i(string)~D  Inserts  the  typed  (string)  into  the  line. 

r(string)~D  Is  identical  to  di(string)~D. 

1  Prints  the  rest  of  the  line,  then  resumes  editing  at  the  begin¬ 

ning. 

p  Prints  the  rest  of  the  line,  then  resumes  editing  at  the  current 

cursor  location. 

u  Restores  the  line  to  its  original  (pre-edited)  state. 

<Newline>  Prints  the  rest  of  the  line,  then  returns  to  the  top-level 
editor. 

Del  or  “C  Aborts  the  interline  edit,  restores  the  line  to  its  original 
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form,  then  returns  to  the  top-level  editor. 

The  commands  (space),  d,  e,  c,  s,  and  k  say  be  preceeded  by  a  signed 
repeat  count  with  the  obvius  result.  (-<command>  *  -I<command> ) .  Also, 
note  that  the  Insert  and  change  commands  only  go  forward  (sigh). 

2)  If  a  hangup  occurs,  the  command  "w  ed-hup"  is  executed  before  the  edi¬ 
tor  exits. 

3)  Prompting  is  default.  Prompting  and  file  counts  may  be  inhibited  with 

the  option  when  invoicing  ed.  In  addition  a  will  alternate  the 

state  of  the  line  number  prompting. 

4)  Line  numbers  at  the  beginning  of  each  line  is  now  the  default.  These 
can  be  turned  on  and  off  using  the  'n'  command. 

5)  'g'  and  'e'  commands  are  Intercepted  the  first  time  if  the  file  has 

been  modified  since  the  last  'e'  command.  Uppercase  Q  and  E  will  execuce 
without  the  warning  message. 

6)  Addressing  outside  the  bounds  of  the  file  will  in  general  be  automati¬ 
cally  corrected  to  within  the  bounds. 

7)  The  bug  which  caused  extra  temp  files  to  file  up  in  / tmp  has  been 

fixed. 

7)  The  ed  command  ' ! '  will,  if  followed  by  a  null  line,  fork  a  shell 

which  remains  in  control  of  the  console  until  an  end-of-file  (~D)  is  re¬ 
ceived. 

9)  The  '1'  command  shows  all  non-graphics,  including  the  177. 

10)  tmp  files  now  take  the  decimal  process  id  as  part  of  their  name. 

(Previously  it  was  the  octal  process  id.) 

11)  “a  and  “h  do  appropriate  things  in  the  o  command. 

12)  The  's'  command  may  now  be  given  without  search  and  replacement 

strings.  The  replacement  strings  as  well  as  the  search  strings  is  remem¬ 
bered  from  the  previous  s  command.  The  g  and  p  suffixes  may  be  used  with 
this  abbreviated  form.  Lower  case  letters  may  no  longer  be  used  as 
search/replacement  string  delimiters. 

13)  The  single  character  command  '/'  and  '?'  may  be  used  where  the  com¬ 

mands  '//'  and  '??'  made  sense  previously. 

14)  The  'z'  command  has  been  added.  Its  syntax  is: 

(.)*(. 1+) (n) 

The  (.)  represents  an  optional  line  address,  n  represents  a  page  size, 
che  number  of  lines  on  a  screen.  If  not  specified,  its  previous  value  is 
used.  The  default  value  is  20.  The  flags  (.1+1-)  specify  che  mode  in 
which  z  is  to  operate. 

.  means  print  che  current  line  in  che  midd’’  of  che  screen; 

-  means  print  the  current  line  at  the  bottom  of  the  screen; 

+  means  print  che  current  line  at  che  top  of  Che  screen.  (The  entire 

screen  is  fill  d  wich  che  necessary  context  lines  to  do  chat.)  +  is  che 

default  and  need  not  be  specified.  Additionally,  if  z+  is  used  wich  no 
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specific  address,  the  line  pointer  is  incremented  before  Z  is  executed* 
Thus  the  Z  command  may  be  used  to  step  through  a  file  page  by  page* 

15)  A  second  temporary  file,  called  /tmp/Exxxxx  where  xxxxx  is  the  process 
id  like  the  first  temporary  has  been  added*  This  contains  indices  into 
/tmp/exxxxx  for  each  line  in  the  ed  file.  The  E  tmp  is  automatically  up¬ 
dated  after  an  r  or  e  command,  and  after  FLUSKLIM  lines  have  been  modi¬ 
fied  by  the  user.  FLUSHLIM  is  currently  set  at  25.  The  buffer  can  also 
be  updated  (like  sync)  by  the  'x'  command.  The  program  "drestore"  takes 
two  files  as  arguments,  the  E  and  e  files  respectively,  and  puts  on  its 
standard  output  the  file  which  ed  had  created.  This  feature  is  essen¬ 
tially  for  restoring  from  crashes,  but  could  become  the  standard  working 
file  format.  Currently,  ed  deletes  its  two  temporaries  whenever  normally 
exited  (though  they  can  be  saved  by  renaming  them  while  in  ed) . 

16)  The  'u'  command  has  been  added*  This  command  will  undo  the  effects  of 
an  s  or  o  edit.  The  last  8  s  and  o  commands  are  saved  on  a  lifo  stack. 

17)  'x<char>'  will  bring  in  the  appropiate  header  from  code  modules,  "es¬ 

cape  cr"  is  used  to  go  to  the  next  subheading.  Presently  the  follwing 
are  supported:  x  no  comment  delimiters  are  provided  xc 

Invokes  "c"  header 

xf  Invokes  the  Fortran  header, 

xa  Invokes  the  assemble  header. 

18)  The  b  command  concerns  itself  with  function  keys  that  can  be  defined  and 

used  in  the  d  editor. 

b  <function  key  definition  file>  .  -  This  will  read  the  file  and  load  the 
function  keys. 

b  -  This  will  list  out  the  values  that  have  been  set  for  the  function 
keys . 

The  set  of  possible  function  keys  is  the  set  of  lower  case  letters.  The 
editor  will  also  set  up  some  default  function  keys  that  relate  to  the 
date. 

The  function  keys  will  operate  in  ac  append  mode  or  in  the  x  command  (see 
x  command).  They  are  invoked  by:  ccontrol  Y>  <f unction  key> 

The  function  key  definition  file  consists  of  separate  lines  to  define 
each  function  key.  The  lines  are  of  the  form:  r<text  to  be  printed  out 
when  the  r  function  key  is  invoked> 

For  example,  a  function  key  definition  such  as  the  following  pProject: 
Pascal  compiler 

would  enter  into  the  (.d.t  file  the  string  "Project:  Pascal  compiler”  when 
<control  Y>p  was  entered. 

The  date  default  keys  are  displayed  and  updated  by  the  b  command.  There 
values  are: 

Y  -  Year 

M  -  Month  of  the  year 
W  -  Week  of  the  month 
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om 


D  -  Day  of  the  month 
H  -  Hour  of  the  day 
N  -  aiNuce  of  the  day 
S  -  Second  of  the  hour 
T  -  Time  In  unix  standard  format 

Suggested  usage  -  Using  the  function  keys  and  a  fora  file  that  Is  read  in 
with  the  x  command  one  is  able  to  generate  flexible  forms  that  can  re¬ 
flect  todays  dace,  the  current  project,  the  users  name  etc. 

19)  'ic<nuai>'  and  'ac<num>'  invoke  modes  that  know  about  'c'  syntax.  Key¬ 
words  are  automatically  generated  using  control  characters.  The  <num>  de¬ 
fines  the  beginning  indentation  level,  during  an  edit  session  this  level 
Is  saved  from  one  c  append  or  Insert  to  the  next.  The  following  is  a  sum¬ 
mary  of  the  various  concrol  character  'escape'  often  used  to  get  to  the 
next  part  of  a  construct. 

concrol  c  escape  carriage 

char  construct  char  return 


char 

break; 

~c 

(exits  append  mode) 

#def ine 

case 

; 

J 

for  ( 

» 

i 

8 

register 

/* 

*/ 

^include  " 

ii 

if 

int 

*0 

main  (argc.argv)  char 

**argv; 

y 

printf ( 

); 

); 

return  ( 

); 

); 

struct 

""t 

switch  ( 

)( 

M 

continue; 

while 

K 

)( 

~x 

extern 

FILES 

/tmp/Exxxxx  index 

file 

/tmp/exxxxx  temporary  edit  file 

/usr/bin/drestore 

crash  restore 

file 
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NAME 

hdl  -  hleracchial  design  language 
SYNOPSIS 

hdl  [-ficl21pug]  [-d  dnamej  [-m  mname]  [-r  rflle]  hdl  files 
DESCRIPTION 

Hdl  Is  a  Cool  that  allows  one  co  describe  a  project,  system  or  module  in 
English,  using  the  higher  level  language  C's  control  flow.  Hdl  provides 
a  verbal  flow  chart  (the  hdl  source),  a  trace  of  the  static  call  struc¬ 
ture,  an  Index  Into  the  hdl  source  to  where  procedures,  globals  and  unde¬ 
fined  procedures  are  used,  and  an  Index  by  page  number  to  all  the  pro¬ 
cedures  and  hdl  segments. 

Hdl  provides  the  following  defaults.  The  hdl  source  Is  reproduced  In  the 
same  format  as  It  was  Input.  Output  format  2,  for  short  procedure  and 
global  names,  Is  used  to  produce  all  hdl  Index  tables.  All  output  Is  for¬ 
matted  for  the  printer.  The  last  and  only  critical  default  Is  chat  unless 
otherwise  Informed  through  the  use  of  the  m  flag,  hdl  will  assume  the 
presence  of  the  top  level  procedure  main. 

-f  Keep  the  procedure  and  global  names  on  files  Instead  of  in 

core.  This  allows  one  to  process  very  large  hdls. 


Input  Specifiers 

-d  dname  Place  the  design  title  dname  In  the  page  header,  which  is 
printed  at  the  top  of  each  page.  The  design  title  Is  limited  co 
a  maximum  length  of  40  characters. 

-m  mname  Use  mname  as  the  top  level  procedure  of  the  hdl. 

-r  rflle  Read  the  file  rflle  to  obtain  the  names  of  the  hdl  source 
files . 


Output  Specifiers 

-1  Indent  the  hdl  source  to  reflect  the  hdl  control  flow. 

-c  Format  the  output  for  the  crt.  Note  that  the  page  sire  has  been 

set  to  be  compatible  with  the  re  (rand)  editor.  This  editor  al¬ 
lows  one  co  examine  a  file  by  page  addressing. 

-1  Format  the  Index  tables  to  accommodate  long  procedure  and  glo¬ 

bal  names. 

-2  Format  the  index  tables  co  accommodate  short  procedure  and  glo¬ 

bal  names.  If  output  is  to  be  formatted  for  the  crt  procedure 
and  global  names  should  be  shorter  than  20  characters,  other¬ 
wise  names  should  be  shorter  than  32  characters.  Note  that  for¬ 
mat  2  will  accommodate  longer  names.  It  may  however,  page  the 
output  incorrectly. 
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Output 

Suppression 

Specifiers 

-1 

Suppress 

printing 

of 

the 

-P 

Suppress 

printing 

of 

the 

-S 

Suppress 

printing 

of 

the 

-u 

Suppress 

printing 

of 

Che 

hdl  source* 

procedure  Index  cable. 

global  index  cable. 

undefined  procedure  index  cable. 


FILES 

/cmp/hdl??? 

/usr/sys/source/udl/hdl 
/us r /bin /hdl 

/usr/sys/ source /ucil/hdl/hdl_doc 


cemporaries 
source  files 
executable  file 
documencacion  file 


SEE  ALSO 

Indenc  (I) 

d  (I)  AuComacic  Indencacion  during  Inpuc  (ac  mode), 
re  (I) 


DIAGNOSTICS 

Syncax  errors  are  reported.  They  normally  involve  unbalanced  double 
quotes,  parentheses  or  curly  brackets* 


BUGS 

Hdl  does  noc  support  pure  C  syntax.  See  hdl_doc  for  syntactical 
anomalies. 
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NAME 

indent  -  produce  an  Indented  c  program  source 
SYNOPSIS 

indent  [ifile  [ofile] ] [args] 

DESCRIPTION 

The  arguments  that  can  be  specified  are: 

ifile  Input  file  specification*  If  this  is  omitted,  input  is  from 
standard  input* 

ofile  Output  file  specification*  If  this  is  omitted,  output  is  to 
standard  output.  Ofile  cannot  be  specified  without  ifile.  -lnnn 
This  gives  the  maximum  length  of  an  output  line.  The  default  is  -1120* 

-cnnn  This  gives  the  column  in  which  comments  will  start.  The  de¬ 
fault  is  -c57. 

-cdnnn  This  gives  the  column  in  which  comments  on  declarations  will 
strt.  The  default  is  for  these  comments  to  start  in  the  same  column  as 
other  comments. 

-innn  This  gives  the  number  of  spaces  for  one  indentation  level.  The 
default  is  -14. 

-dj ,-ndg  -dj  will  cause  declarations  to  be  left  justified.  -ndj  will 
cause  them  to  be  indented  the  same  as  code.  The  default  is  -14. 

-v,-nv  -v  turns  on  "verbose"  mode,  -nv  turns  it  off.  When  in  verbose 
mode,  indent  will  report  when  it  splits  one  line  of  input  into  two  or 
more  lines  of  output,  and  it  will  give  some  size  statistics  at  comple¬ 
tion.  The  default  is  -nv. 

-bc,-nbc  If  -be  is  specified,  then  a  newline  will  be  forced  after  each 
comma  in  a  declaraction.  -nbc  will  turn  off  this  option.  The  default 
is-bc. 

-dnnn  This  option  controls  the  placement  of  comments  which  are  not  to 
the  right  of  code.  The  default  of  -d2  means  that  such  comments  will  be 
placed  two  indentation  levels  to  the  left  of  code.  -do  would  line  up 
such  comments  with  the  code.  See  the  section  on  comment  indentation 
below. 

-br,-bl  Specifying  -bl  will  cause  complex  statements  to  be  lned  up 
like  this: 

if  (...) 

{ 

code 

} 

Specifying  -br  will  make  them  look  like  this: 
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If  (-..){ 
code 

> 

The  defaulc  is  -bl. 

Indent  is  Intended  primarily  as  a  c  program  indenter.  It  will  not  cake 
an  arbitrary  c  program  and  produce  a  source  file  which  conforms  to  the 
dsg  documentation  standards.  It  will,  however,  isolate  Che  programmer 
from  much  of  the  work,  required  to  get  his/her  source  into  such  a  format. 
Specifically,  indent  will: 

indent  code  lines 
align  commencs 

insert  spaces  around  operators,  where  necessary 
break  up  declaration  lists,  as  in  "inc  a,b,c;". 

It  will  not  break  up  long  statements  to  make  them  fit  within  the  maximum 
line  length,  but  it  will  flag  lines  that  are  coo  long.  Lines  will  be 
broken  so  that  each  statement  starts  a  new  line,  and  braces  will  appear 
alone  on  a  line,  (see  che  -br  optin  for  the  exception  to  this.)  also,  a 
feeble  attempt  is  mde  to  line  up  identifiers  in  declarations. 

multi-line  expressions 

Indent  will  not  break  up  complicated  expressions  that  extend  over  multi¬ 
ple  lines,  but  it  will  usually  correctly  Indent  such  expressions  which 
have  already  been  broken  up.  Such  an  expression  might  end  up  looking 
like  this: 

x  ■ 

( 

(arbitrary  parenthesized  expression) 

+ 

( 

(parenthesized  expression) 

* 

(parenthesized  expression) 

) 

)i 

COMMENTS 

Indent  recognizes  four  kinds  of  comments.  They  are  straight  text,  "box" 
commencs,  unlx-scyle  comments,  and  comments  that  should  be  passed  through 
unchanged-  The  action  taken  with  these  various  types  is  as  follows: 

"box"  comments:  The  dsg  documentation  standards  specify  chat  boxes  will 
be  placed  around  section  headers.  Indent  essumes  chat  any  commencs  with 
a  dash  Immediately  after  che  start  of  comment  (l.e.  "/*-")  is  such  a  box. 
Each  line  of  such  a  comment  will  be  left  unchanged,  except  that  the  first 
non-blank  character  of  each  successive  line  will  be  lined  up  with  the  be¬ 
ginning  slash  of  che  first  line.  Box  comments  will  be  ldenced  (see 
below).  Unlx-scyle  comments:  This  is  the  type  of  section  header  which 
is  used  extensively  in  che  unlx  system  source.  If  che  start  of  comment 
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('/*')  appears  on  a  line  by  itself,  indent  assumes  that  it  is  a  Unix- 
style  comment.  These  will  be  treated  similarly  to  box  comments,  except 
the  first  non-blank  character  on  each  line  will  be  lined  up  with  the 
of  the  '/*'•  Unchanged  comments:  any  comment  which  starts  in  column  1 
will  be  left  completely  unchanged.  This  is  intended  primarily  for  docu¬ 
mentation  header  pages.  The  check  for  unchanged  comments  is  made  before 
the  check  for  unix-style  comments.  Straight  text:  all  other  comments 

are  treated  as  straight  text.  Indent  will  fit  as  many  words  (separated 
by  blanks,  tabs,  or  possible.  Straight  text  comments  will  be  Indented. 

Comment  indentation 

Box,  unix-style  and  straight  text  comments  may  be  Indented.  If  a  comment 
is  on  line  with  code,  or  followlns  a  non-blank  line,  it  will  be  started  in 
the  "comment  column",  which  is  set  by  the  arameter.  Otherwise,  the  com¬ 
ment  will  be  started  at  nnn  Indentation  levels  less  than  where  code  is 
currently  being  placed.  Vhere  nnn  is  specified  by  the  -dnnn  command  line 
parameter.  (Indented  comments  will  never  be  placed  in  column  1.) 

If  the  code  on  a  line  extends  past  the  comment  column,  the  comment  will 
be  moved  to  the  next  line. 


Diagnostics 

Diagnostic  error  messages,  mostly  to  tell  that  a  code  line  has  been  bro¬ 
ken  or  is  too  long  for  the  output  line,  will  be  printed  on  the  control¬ 
ling  tty. 


Bugs 

None  known  at  this  writing,  but  they  surely  exist.  If  (when)  any  are 
found,  plese  notify  David  Willcox. 
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NAME 

nn  -  print  n-squared  tree  of  procedure  calling  structure 
SYNOPSIS 

an  source  file  ... 

DESCRIPTION 

tin  Invokes  cref  to  produce  the  temporary  file  produced  by  cref.  It  then, 
using  this  temporary  file,  produces  an  n-squared  type  tree  of  the  calling 
structure.  The  default  mode  assumes  that  the  top  of  the  tree  is  the  pro¬ 
cedure  main. 

-m  Use  the  first  argument  following  the  flags  as  the  cop  of  the  tree. 

-c  Include  all  calls  to  the  C  library  in  the  procedure  tree. 

-g  Print  out  globals. 

-s  Sort  all  oucpuc. 

-d  Delete  all  duplicates  and  sort  all  output.  All  duplicate  globals  are 
removed  and  also  all  duplicate  procedures  on  any  level  are  removed. 

-h  Print  active  procedure  list  at  the  top  of  each  page.  This  is  useful 
if  a  very  large  tree  is  to  be  printed. 


FILES 

/tmp/nn??  temporary  files 

/usr/sys/nsource/ucil/nn  source  files 
/usr/bin/nn  executable  file 

SEE  ALSO 

cref (I) 

DIAGNOSTICS 

If  more  chan  one  top  of  tree  is  found  the  message: 

"  multiple  cop  of  tree  found  " 

will  print  out.  Nn  will  use  the  first  top  of  tree  it  finds  as  the  cop  of 
the  oucpuc  tree.  One  should  check  the  files  chat  were  given  to  nn.  See 
BUGS. 


BUGS 

If  files  with  multiple  versions  of  the  same  procedures  are  passed  to  nn, 
nn  will  produce  a  tree  that  is  a  mixture  of  these  versions. 

Cref  incorrectly  scans  procedure  type  declarations  as  procedure  defini¬ 
tions.  Since  nn  post-processes  cref  output,  this  error  is  passed  on. 
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Ford  Aerospace  &  Communications  Corporation 
Western  Development  Laboratories 
Software  Technology  Department 
3939  Fabian  Way 
Palo  Alto,  California  94303 

ABSTRACT 


This  paper  presents  guidelines  and  standards  for  the  docu¬ 
mentation  of  UNIX  software  for  release  to  external  organizations. 
The  rationale  is  to  provide  the  minimum  level  of  documentation 
necessary  to  make  programs  easy  to  use,  understand,  and  support. 


1 .  General  Rules 

Documentation  for  a  UNIX  software  distribution  package  should  consist  of 
the  following  items: 

*  Installation  guide. 

*  Page(s)  for  the  UNIX  Programmer's  Reference  Manual. 

*  User's  guide  or  Manual. 

*  Technical  manual  or  software  notebook  pages. 

As  may  be  expected,  one  or  more  of  these  items  may  be  missing  or  combined. 
The  installation  guide  may  be  an  appendix  to  the  technical  manual,  or  both  the 
software  notebook  and  the  installation  guide  may  be  included  as  the  first  few 
pages  of  the  actual  software. 

1.1.  General  Format  and  Preparation 

All  machine  readable  documentation  should  be  in  a  format  to  be  input  to 
the  nroff  program  (nroff  source).  This  is  no  hardship  to  anyone  since  all 
UNIX  systems  have  nroff. 

Whenever  possible  use  a  "standard"  macro  package  for  the  files.  Good 
choices  are  the  ”ms"  [1]  or  the  "mm"  [2]  packages.  The  primary  reason  for 
this  requirement  is  to  ensure  that  the  site  using  the  package  has  the 
appropriate  macros.  Also,  both  of  the  above  packages  can  be  used  with  the 
photo-composition  typesetter,  which  most  "home  brew"  packages  cannot. 


[1]  The  package  tmac.ms  is  distributed  with  the  standard  UNIX  system. 

[2]  The  package  tmac.mm  is  provided  with  the  Programmer's  Workbench  system. 
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All  documents  having  more  chan  one  part  (chapter,  section)  should  have  a 
master  file  sec  up  as  follows: 

•?o  begin 
•so  next 

•  so  cha,;'-! 

•so  last 
•so  call 

This  Is  co  allow  a  user  Co  be  able  to  understand  how  to  generate  che  document. 
The  user  should  be  able  co  say: 
nroff  file  or, 
croff  file 

Please  noce  chat  due  co  differences  in  line  prlnCers  and  terminals  page 
lengths  are  noc  always  che  same  and  Che  files  should  allow  for  this  parameter 
co  be  changed  easily. 

All  macros  should  be  referenced  by  che  following  method: 

•so  /usr/lib/emac.s 

This  leaves  no  doubc  co  che  user  as  co  whac  to  do  co  generate  che  file  or 
where  che  macros  are  expected  co  be. 


2.  Installation  Guide 

The  Installation  guide  should  provide  all  necessary  information  co 
install  che  software.  It  may  be  a  separate  manual,  lc  may  be  included  In  che 
technical  manual  or  software  notebook,  or  it  could  be  a  README  file  in  che 
directory  wich  che  software. 

2.1.  Cover  Letter 

A  general  cover  letter  should  be  Included  describing  Che  concents  of  che 
package.  It  should  provide  Che  following  information: 

*  any  restrictions,  proprietary  or  legal  concerning  Che  package  such  as 
second  or  third  pare  licenses  required. 

*  general  overview  and  description  of  the  package.  If  the  package* is  dis¬ 
tributed  on  cape  a  description  on  how  the  cape  is  organized.  (This  should 
include  a  listing  of  all  files  see  section  2.4.) 

*  Instructions  as  co  how  to  extract  the  software  and  where  co  place  it  in 
che  UNIX  dlreccory  system.  If  che  cape  Is  a  tp  Cape,  Information  as  co 
whac  files  co  extract  first,  etc. 

2.2.  Installation  Procedures 

A  detailed  step  by  step  procedure  co  install  the  software.  No  step  is 
too  small  co  Include,  no  detail  Is  coo  small  co  mention.  A  Heachklc-cype  pro¬ 
cedure  is  recommended. 
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2. 2.1.  Install  Object  Programs 

If  the  tape  has  pre-compiled  object  programs,  there  should  be  instruc¬ 
tions  on  how  to  Install  these  in  their  proper  places* 

2.2.2.  Compile  Sources 

This  should  specify  exact  sequences  for  compiling  sources.  It  should 

give  command  strings  to  use  including  any  special  switches  (e.g.,  -n,  -i ,  or 
-Ip).  Also  list  any  special  libraries  to  include  files  needed. 

2.2.3.  Test  Software 

This  should  describe  how  to  test  the  software  for  correct  operation.  It 
might  involve  the  use  of  special  test  programs. 

2.3.  Shell  or  Run  Files 

A  copy  of  all  shell  or  run  files  should  be  Included  in  the  installation 
guide  so  they  can  be  read  and  digested  before  use. 

2.4.  List  of  Files  and  Directories 

A  list  of  all  files  and  directories  on  the  distribution  medium  (tape) 
should  be  given  with  a  description  of  the  use  or  meaning  of  each. 

2.3.  Appendix 

The  following  items  should  also  be  given: 

*  A  list  of  all  programs  or  files  to  be  placed  in  the  public  file  spaces  of 
Che  system 

*  A  list  of  all  embedded  or  compiled  file  names  (or  user  names  or  ids)  and 
the  modules  in  which  they  appear 

*  A  list  of  all  libraries,  routines  and  modules  required  which  are  not  part 
of  the  Version  6  UNIX 

*  A  list  of  any  "non-standard"  features  or  operating  system  calls  (those 
not  in  Version  6.0  of  UNIX) 

*  All  include  files  required  and  where  they  should  be  located 

*  All  documentation  macros  that  are  not  distributed  as  part  of  UNIX. 

One  may  fairly  assume  that  copies  of  Che  UNIX  User's  Group  software  distribu¬ 
tion  center  tapes  are  generally  available  and  can  be  referred  to  for  copies  of 
specific  items.  Do  not  assume  that  all  (or  any)  of  that  software  has  been 
installed,  since  many  installations  are  still  running  a  standard  distribution 
version  of  UNIX. 

2.6.  README  Files 

If  software  packages  have  special  files  such  as  README  files  they  should 
also  be  included. 
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2.7.  Manual  Pages 

We  recommend  adding  a  macro  .RV  co  Che  manual  macros  as  follows: 

.RV  who  when  where 

The  who  specifies  che  last  person  Co  revise  che  manual  page.  The  when  gives 
che  dace  of  revision.  The  where  gives  che  sources  of  che  software  (such  as 
RAND ,  USNPGS,  CAC,  SDC1,  ecc.)  This  line  of  lnformaclon  is  printed  at  che  bot¬ 
tom  of  each  manual  page.  Remember  chat  more  chan  one  manual  page  is  required 
if  special  formats  or  files  are  involved. 


3.  User's  Manual 

Often,  more  information  is  required  chan  the  format  of  the  standard 
manual  page  provides.  The  following  subsections  suggesc  some  helpful  addi¬ 
tions  to  the  information  contained  in  che  manual. 

3.1.  Error  Messages  and  Diagnostics 

A  listing  of  all  possible  diagnostics  generated  by  che  software  Informs 
the  user  of  the  kind  of  error  conditions  he  may  expect.  Suggestions  for 
corrective  action  co  be  taken  by  che  user  would  also  be  extremely  helpful. 

3.2.  Usage  Distributions 

In  order  co  help  che  user  get  started,  include  a  sample  usage  session 
with  che  progr3m(s) .  To  guarantee  authenticity,  the  command  script  and  program 
responses  should  be  collected  from  an  actual  session. 


4.  Technical  Manual 

This  manual  is  sometimes  called  a  software  notebook.  It  should  contain 
everything  an  unfamiliar  systems  programmer  needs  co  know  about  che  software 
in  order  co  maintain  it. 

Again,  there  are  standards  for  such  manuals  and  this  paper  covers  only 
UNIX  related  areas. 

4.1.  Narrative  Overview 

This  could  be  a  short  version  of  the  preliminary  design  specification. 
It  should  give  a  brief  description  of  what  che  program  does  and  how  it  does 
it.  Specific  UNIX  concepts  and  features  such  as  pipes,  lock  files,  signals, 
temp  files,  and  inter-process  communication  primitives  are  to  be  used.  Tor 
example,  "The  program  spawns  a  child  process  which  does  an  execl  of  'car 
/usr /help/tom.hf '  co  present  the  help  information." 
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4.2.  User  Interface 

Describe  the  behavior  of  the  program  exactly  as  the  user  sees  it.  Items 
of  special  Interest  might  Include  the  fact  that  input  is  done  in  raw  mode,  or 
that  the  program  traps  the  interrupt  signal. 

4.3.  Data  Structures 

Describe  each  significant  data  structure  used  by  the  program.  For  each 
field  the  meaning  of  the  field  and  the  range  of  allowed  values  should  be 
given. 


4.4.  Files 

There  shold  be  a  listing  of  all  files  used  or  generated  by  the  program 
(with  full  path  names).  (Include  implicit  files  such  as  the  /etc/psswd  file 
used  by  getpw. )  Normal  system  files  need  not  have  formats  specified,  but  their 
use  should  be  noted. 


5.  Summary 

The  purpose  of  documentation  is  to  allow  a  person  who  has  never  seen  the 
software  package  to  Install,  use,  and  maintain  it  with  minimal  effort.  The 
last  thing  one  should  do  before  releasing  the  documentation  for  a  software 
product  is  to  give  it  to  a  stranger  and  ask  him  to  use  it  or  to  install  the 
software. 
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